Hyperfold AI

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.

EndpointMethodDescription
/v1/projectsPOSTCreate a new project
/v1/projectsGETList all projects
/v1/projects/:idGETGet project details
/v1/projects/:idPATCHUpdate project
/v1/projects/:idDELETEDelete project
/v1/projects/:id/settingsGET/PATCHManage project settings

Create Project

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# 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

FieldTypeRequiredDescription
namestringYesDisplay name for the project
slugstringYesURL-safe identifier (unique)
descriptionstringNoProject description
settingsobjectNoInitial project settings

List Projects

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# 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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# 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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# 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.