Hyperfold AI

API Overview

RESTful APIs for managing your Hyperfold commerce infrastructure.

Introduction

The Hyperfold API provides programmatic access to all platform features. Use the API to manage your catalog, deploy agents, configure integrations, and access analytics data.

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Example API request
curl -X POST https://api.hyperfold.io/v1/catalog/products \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Project-ID: proj_acme" \
  -d '{
    "name": "Running Shoes Pro",
    "sku": "SHOE-001",
    "price": 129.99,
    "category": "footwear"
  }'
 
# Response
{
  "id": "prod_abc123",
  "name": "Running Shoes Pro",
  "sku": "SHOE-001",
  "price": 129.99,
  "category": "footwear",
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-20T10:00:00Z"
}

API Types

Hyperfold provides two API categories for different use cases:

APIPurposeDocs
Management APIBackend operations: catalog, agents, integrations, analyticsManagement API
ACP APIBuyer-facing: search, negotiate, checkout (Agentic Commerce Protocol)ACP API

Management API

Server-to-server API for managing your Hyperfold resources:

ACP API

The Agentic Commerce Protocol API is exposed by your agents for buyer interactions:

Base URLs

EnvironmentBase URL
Productionhttps://api.hyperfold.io/v1
Sandboxhttps://sandbox.api.hyperfold.io/v1
ACP (your domain)https://acp.yourdomain.com

Versioning

The API uses URL path versioning. The current version is v1. When breaking changes are introduced, a new version will be released with a migration period.

API version is included in the URL path: /v1/catalog/products. We maintain backwards compatibility within major versions.

Rate Limits

API requests are rate-limited to ensure platform stability:

PlanRequests/minBurst
Starter100150
Growth1,0001,500
Enterprise10,000+Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705750800

Error Handling

json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Error response format
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": [
      {
        "field": "price",
        "message": "Price must be a positive number"
      }
    ],
    "request_id": "req_xyz789"
  }
}
 
# Common error codes
400 Bad Request        - Invalid request syntax or parameters
401 Unauthorized       - Missing or invalid authentication
403 Forbidden          - Insufficient permissions
404 Not Found          - Resource doesn't exist
409 Conflict           - Resource state conflict
422 Unprocessable      - Validation errors
429 Too Many Requests  - Rate limit exceeded
500 Internal Error     - Server-side error

SDKs

Official SDKs handle authentication, rate limiting, and error handling:

typescript
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
// TypeScript/JavaScript SDK
import { Hyperfold } from '@hyperfold/sdk';
 
const client = new Hyperfold({
  apiKey: process.env.HYPERFOLD_API_KEY,
  projectId: 'proj_acme'
});
 
// Create a product
const product = await client.catalog.products.create({
  name: 'Running Shoes Pro',
  sku: 'SHOE-001',
  price: 129.99
});
 
// List products with filtering
const products = await client.catalog.products.list({
  category: 'footwear',
  limit: 20
});
 
// Python SDK
from hyperfold import Hyperfold
 
client = Hyperfold(
    api_key=os.environ["HYPERFOLD_API_KEY"],
    project_id="proj_acme"
)
 
product = client.catalog.products.create(
    name="Running Shoes Pro",
    sku="SHOE-001",
    price=129.99
)
Next: Set up API Authentication.