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.

# 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:

API	Purpose	Docs
Management API	Backend operations: catalog, agents, integrations, analytics	Management API
ACP API	Buyer-facing: search, negotiate, checkout (Agentic Commerce Protocol)	ACP API

Management API

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

Projects - Create and manage projects
Catalog - Product and inventory management
Agents - Deploy and configure agents
Finance - Payments, wallets, transactions
Integrations - External system connections

ACP API

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

Discovery - Capability manifest and search
Commerce - Quotes, negotiation, checkout
Post-Purchase - Order status, returns, support

Base URLs

Environment	Base URL
Production	`https://api.hyperfold.io/v1`
Sandbox	`https://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:

Plan	Requests/min	Burst
Starter	100	150
Growth	1,000	1,500
Enterprise	10,000+	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 950

X-RateLimit-Reset: 1705750800

Error Handling

# 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/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.

Search Documentation