Projects API

Create and manage Hyperfold projects programmatically.

Overview

Projects are the top-level organizational unit in Hyperfold. Each project contains its own catalog, agents, integrations, and settings. Use the Projects API to manage multiple storefronts or environments.

Endpoint	Method	Description
`/v1/projects`	POST	Create a new project
`/v1/projects`	GET	List all projects
`/v1/projects/:id`	GET	Get project details
`/v1/projects/:id`	PATCH	Update project
`/v1/projects/:id`	DELETE	Delete project
`/v1/projects/:id/settings`	GET/PATCH	Manage project settings

Create Project

# POST /v1/projects
# Create a new project
curl -X POST https://api.hyperfold.io/v1/projects \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Sports Store",
    "slug": "acme-sports",
    "description": "E-commerce platform for sports equipment",
    "settings": {
      "default_currency": "USD",
      "timezone": "America/Los_Angeles",
      "locale": "en-US"
    }
  }'
# Response (201 Created)
{
  "id": "proj_abc123",
  "name": "Acme Sports Store",
  "slug": "acme-sports",
  "description": "E-commerce platform for sports equipment",
  "settings": {
    "default_currency": "USD",
    "timezone": "America/Los_Angeles",
    "locale": "en-US"
  },
  "status": "active",
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-20T10:00:00Z",
  "endpoints": {
    "acp": "https://acp.acme-sports.hyperfold.app",
    "api": "https://api.hyperfold.io/v1"
  }
}

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name for the project
`slug`	string	Yes	URL-safe identifier (unique)
`description`	string	No	Project description
`settings`	object	No	Initial project settings

List Projects

# GET /v1/projects
# List all projects for the authenticated account
curl -X GET "https://api.hyperfold.io/v1/projects?limit=20&offset=0" \
  -H "Authorization: Bearer hf_live_xxx"
# Response
{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Acme Sports Store",
      "slug": "acme-sports",
      "status": "active",
      "created_at": "2025-01-20T10:00:00Z"
    },
    {
      "id": "proj_def456",
      "name": "Acme Apparel",
      "slug": "acme-apparel",
      "status": "active",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}
# GET /v1/projects/:id
# Get a specific project
curl -X GET https://api.hyperfold.io/v1/projects/proj_abc123 \
  -H "Authorization: Bearer hf_live_xxx"
# Response includes full project details with statistics
{
  "id": "proj_abc123",
  "name": "Acme Sports Store",
  "slug": "acme-sports",
  "settings": { ... },
  "status": "active",
  "statistics": {
    "products": 2847,
    "agents": 4,
    "orders_30d": 1234,
    "revenue_30d": 187450.00
  },
  "integrations": [
    {"type": "shopify", "status": "connected"},
    {"type": "stripe", "status": "connected"}
  ]
}

Update Project

# PATCH /v1/projects/:id
# Update project details
curl -X PATCH https://api.hyperfold.io/v1/projects/proj_abc123 \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Sports Pro",
    "settings": {
      "default_currency": "USD",
      "timezone": "America/New_York",
      "negotiation_enabled": true,
      "max_discount_percent": 25
    }
  }'
# Response (200 OK)
{
  "id": "proj_abc123",
  "name": "Acme Sports Pro",
  "settings": {
    "default_currency": "USD",
    "timezone": "America/New_York",
    "negotiation_enabled": true,
    "max_discount_percent": 25
  },
  "updated_at": "2025-01-20T11:00:00Z"
}
# DELETE /v1/projects/:id
# Delete a project (requires confirmation)
curl -X DELETE https://api.hyperfold.io/v1/projects/proj_abc123 \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Confirm-Delete: proj_abc123"
# Response (204 No Content)

Deleting a project permanently removes all associated data including products, orders, and agent configurations. This action cannot be undone.

Project Settings

# GET /v1/projects/:id/settings
# Get detailed project settings
curl -X GET https://api.hyperfold.io/v1/projects/proj_abc123/settings \
  -H "Authorization: Bearer hf_live_xxx"
# Response
{
  "general": {
    "name": "Acme Sports Pro",
    "slug": "acme-sports",
    "timezone": "America/New_York",
    "locale": "en-US",
    "default_currency": "USD"
  },
  "commerce": {
    "negotiation_enabled": true,
    "max_discount_percent": 25,
    "bundle_suggestions": true,
    "subscription_enabled": false
  },
  "agents": {
    "default_llm_provider": "openai",
    "default_llm_model": "gpt-4-turbo",
    "max_tokens_per_request": 4096,
    "temperature": 0.7
  },
  "notifications": {
    "email_enabled": true,
    "slack_webhook": "https://hooks.slack.com/...",
    "alert_channels": ["email", "slack"]
  },
  "security": {
    "ip_allowlist": [],
    "mfa_required": true,
    "session_timeout_minutes": 60
  }
}
# PATCH /v1/projects/:id/settings
# Update specific settings
curl -X PATCH https://api.hyperfold.io/v1/projects/proj_abc123/settings \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "commerce": {
      "max_discount_percent": 30
    },
    "agents": {
      "temperature": 0.5
    }
  }'

Settings Categories

General

Basic project information like name, timezone, and locale settings.

Commerce

Business rules including negotiation limits, bundle settings, and subscription options.

Agents

Default LLM provider, model selection, and inference parameters.

Security

IP allowlists, MFA requirements, and session management.

Next: Manage your product Catalog API.

Search Documentation