Hyperfold AI

Catalog API

Manage products, inventory, and categories in your Hyperfold catalog.

Overview

The Catalog API provides full CRUD operations for your product catalog, including inventory management, category organization, and semantic search.

ResourceEndpoints
ProductsCRUD operations, variants, pricing
InventoryStock levels, locations, adjustments
CategoriesHierarchical organization
SearchSemantic product search

Products

Create Product

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
# POST /v1/catalog/products
# Create a new product
 
curl -X POST https://api.hyperfold.io/v1/catalog/products \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AeroRun X2 Waterproof",
    "sku": "SHOE-AERO-X2",
    "description": "Professional marathon shoe with Gore-Tex lining",
    "price": 179.99,
    "cost": 72.00,
    "category": "footwear/running",
    "brand": "AeroRun",
    "attributes": {
      "material": "Gore-Tex",
      "weight": "280g",
      "waterproof": true
    },
    "variants": [
      {"sku": "SHOE-AERO-X2-BLK-9", "size": "9", "color": "black", "inventory": 25},
      {"sku": "SHOE-AERO-X2-BLK-10", "size": "10", "color": "black", "inventory": 30},
      {"sku": "SHOE-AERO-X2-BLU-9", "size": "9", "color": "blue", "inventory": 20}
    ],
    "images": [
      {"url": "https://cdn.example.com/aero-x2-main.jpg", "position": 1},
      {"url": "https://cdn.example.com/aero-x2-side.jpg", "position": 2}
    ],
    "semantic_tags": ["marathon", "waterproof", "professional", "lightweight"],
    "negotiation": {
      "enabled": true,
      "floor_price": 135.00,
      "target_margin": 0.45
    }
  }'
 
# Response (201 Created)
{
  "id": "prod_abc123",
  "name": "AeroRun X2 Waterproof",
  "sku": "SHOE-AERO-X2",
  "price": 179.99,
  "status": "active",
  "created_at": "2025-01-20T10:00:00Z",
  "variants_count": 3,
  "total_inventory": 75
}

List and Get Products

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
# GET /v1/catalog/products
# List products with filtering and pagination
 
curl -X GET "https://api.hyperfold.io/v1/catalog/products?\
category=footwear&\
min_price=100&\
max_price=200&\
in_stock=true&\
limit=20" \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
 
# Response
{
  "data": [
    {
      "id": "prod_abc123",
      "name": "AeroRun X2 Waterproof",
      "sku": "SHOE-AERO-X2",
      "price": 179.99,
      "category": "footwear/running",
      "in_stock": true,
      "total_inventory": 75
    }
  ],
  "meta": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "filters_applied": {
      "category": "footwear",
      "price_range": [100, 200],
      "in_stock": true
    }
  }
}
 
# GET /v1/catalog/products/:id
# Get full product details
 
curl -X GET https://api.hyperfold.io/v1/catalog/products/prod_abc123 \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"

Product Fields

FieldTypeDescription
semantic_tagsarrayTags for semantic search matching
negotiation.floor_pricenumberMinimum price agent can accept
negotiation.target_marginnumberTarget profit margin (0-1)
variantsarrayProduct variants (size, color, etc.)

Inventory

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
56
57
58
# GET /v1/catalog/inventory
# Get inventory levels across all products
 
curl -X GET "https://api.hyperfold.io/v1/catalog/inventory?\
location=loc_la_001&\
low_stock=true" \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
 
# Response
{
  "data": [
    {
      "sku": "SHOE-AERO-X2-BLK-9",
      "product_id": "prod_abc123",
      "product_name": "AeroRun X2 Waterproof",
      "location": "loc_la_001",
      "quantity": 5,
      "reserved": 2,
      "available": 3,
      "reorder_point": 10,
      "status": "low_stock"
    }
  ],
  "summary": {
    "total_skus": 2847,
    "low_stock": 142,
    "out_of_stock": 23
  }
}
 
# PATCH /v1/catalog/inventory/:sku
# Update inventory for a SKU
 
curl -X PATCH https://api.hyperfold.io/v1/catalog/inventory/SHOE-AERO-X2-BLK-9 \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "adjustment": 50,
    "reason": "restock",
    "location": "loc_la_001"
  }'
 
# POST /v1/catalog/inventory/bulk
# Bulk inventory update
 
curl -X POST https://api.hyperfold.io/v1/catalog/inventory/bulk \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"sku": "SHOE-AERO-X2-BLK-9", "quantity": 50, "location": "loc_la_001"},
      {"sku": "SHOE-AERO-X2-BLK-10", "quantity": 45, "location": "loc_la_001"},
      {"sku": "SHOE-AERO-X2-BLU-9", "quantity": 30, "location": "loc_la_001"}
    ]
  }'

Categories

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
# GET /v1/catalog/categories
# List all categories
 
curl -X GET https://api.hyperfold.io/v1/catalog/categories \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
 
# Response
{
  "data": [
    {
      "id": "cat_footwear",
      "name": "Footwear",
      "slug": "footwear",
      "product_count": 456,
      "children": [
        {"id": "cat_running", "name": "Running", "slug": "footwear/running", "product_count": 123},
        {"id": "cat_hiking", "name": "Hiking", "slug": "footwear/hiking", "product_count": 89}
      ]
    },
    {
      "id": "cat_apparel",
      "name": "Apparel",
      "slug": "apparel",
      "product_count": 892
    }
  ]
}
 
# POST /v1/catalog/categories
# Create a category
 
curl -X POST https://api.hyperfold.io/v1/catalog/categories \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trail Running",
    "slug": "footwear/running/trail",
    "parent_id": "cat_running",
    "description": "Shoes designed for off-road running"
  }'

Search

Semantic search uses vector embeddings to find products matching natural language queries:

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
# POST /v1/catalog/search
# Semantic search across catalog
 
curl -X POST https://api.hyperfold.io/v1/catalog/search \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "waterproof shoes for marathon running",
    "filters": {
      "category": "footwear",
      "price_max": 200,
      "in_stock": true
    },
    "limit": 10,
    "include_semantic_scores": true
  }'
 
# Response
{
  "results": [
    {
      "id": "prod_abc123",
      "name": "AeroRun X2 Waterproof",
      "price": 179.99,
      "semantic_score": 0.94,
      "match_reasons": ["waterproof", "marathon", "professional running shoe"]
    },
    {
      "id": "prod_def456",
      "name": "TrailMaster Pro",
      "price": 159.99,
      "semantic_score": 0.82,
      "match_reasons": ["waterproof", "running shoe"]
    }
  ],
  "meta": {
    "query_time_ms": 45,
    "total_results": 8,
    "semantic_model": "text-embedding-3-large"
  }
}
Semantic search is powered by the same vector database used by your agents. Products are automatically indexed when created or updated.
Next: Deploy and manage Agents API.