Hyperfold AI

ACP Discovery API

Endpoints for buyer agents to discover products and merchant capabilities.

Overview

The ACP Discovery API allows buyer agents to understand what your store offers and search for products. These endpoints are exposed by your Negotiator Agent and follow the Agentic Commerce Protocol specification.

Discovery endpoints don't require authentication. They're designed for open access by buyer agents to facilitate commerce discovery.

Manifest

The manifest endpoint announces your merchant capabilities to buyer agents:

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 /.well-known/acp/manifest.json
# Discover merchant capabilities
 
curl -X GET https://acp.acme.hyperfold.app/.well-known/acp/manifest.json
 
# Response
{
  "acp_version": "1.0",
  "merchant": {
    "id": "merchant_acme",
    "name": "Acme Sports",
    "description": "Premium sports equipment and apparel",
    "logo_url": "https://cdn.acme.com/logo.png",
    "capabilities": ["negotiate", "bundle", "subscribe", "recommend"]
  },
  "endpoints": {
    "search": "/acp/search",
    "product": "/acp/products/{id}",
    "quote": "/acp/quote",
    "checkout": "/acp/checkout/init",
    "finalize": "/acp/checkout/finalize",
    "orders": "/acp/orders/{id}",
    "returns": "/acp/returns"
  },
  "payment_methods": [
    {"type": "stripe_spt", "currencies": ["USD", "EUR", "GBP"]},
    {"type": "paypal_ba", "currencies": ["USD"]}
  ],
  "supported_currencies": ["USD", "EUR", "GBP"],
  "shipping_regions": ["US", "CA", "EU"],
  "policies": {
    "negotiation_enabled": true,
    "max_discount_percent": 20,
    "return_window_days": 30,
    "free_shipping_threshold": 75.00
  },
  "categories": [
    {"id": "footwear", "name": "Footwear", "product_count": 456},
    {"id": "apparel", "name": "Apparel", "product_count": 892},
    {"id": "equipment", "name": "Equipment", "product_count": 234}
  ]
}

Manifest Fields

FieldDescription
capabilitiesWhat the merchant can do (negotiate, bundle, etc.)
endpointsAvailable API endpoints
payment_methodsAccepted payment methods
policiesBusiness policies (returns, shipping thresholds)

Search

Semantic search allows buyer agents to find products using natural language:

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
59
60
61
62
63
64
65
66
# POST /acp/search
# Semantic product search
 
curl -X POST https://acp.acme.hyperfold.app/acp/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "waterproof running shoes for marathon",
    "filters": {
      "category": "footwear",
      "price_max": 200,
      "size": "10",
      "color_preference": ["blue", "black"]
    },
    "limit": 10,
    "buyer_context": {
      "loyalty_tier": "gold",
      "location": "US",
      "purchase_history": 12
    }
  }'
 
# Response
{
  "session_id": "sess_abc123",
  "results": [
    {
      "product_id": "prod_aero_x2",
      "name": "AeroRun X2 Waterproof",
      "description": "Professional marathon shoe with Gore-Tex lining",
      "brand": "AeroRun",
      "list_price": 179.99,
      "negotiable": true,
      "semantic_match": {
        "score": 0.94,
        "reasons": ["waterproof", "marathon", "professional running"]
      },
      "images": [
        {"url": "https://cdn.acme.com/aero-x2.jpg", "alt": "AeroRun X2"}
      ],
      "availability": {
        "in_stock": true,
        "quantity": 45,
        "shipping_estimate": "2-3 days"
      },
      "variants": [
        {"size": "10", "color": "blue", "in_stock": true},
        {"size": "10", "color": "black", "in_stock": true}
      ]
    }
  ],
  "total_count": 8,
  "facets": {
    "brands": [{"name": "AeroRun", "count": 3}, {"name": "TrailMaster", "count": 2}],
    "price_ranges": [{"min": 100, "max": 150, "count": 3}, {"min": 150, "max": 200, "count": 5}],
    "colors": [{"name": "blue", "count": 4}, {"name": "black", "count": 6}]
  },
  "recommendations": [
    {
      "type": "complementary",
      "product_id": "prod_socks_wp",
      "name": "Waterproof Running Socks",
      "price": 29.99,
      "bundle_discount": "15%"
    }
  ]
}

Search Features

Semantic Matching

Queries are understood semantically, not just keyword-matched. "Waterproof marathon shoes" finds relevant products even if those exact words aren't in the product description.

Buyer Context

Passing buyer context enables personalized results. Gold members might see different pricing or product recommendations.

Faceted Results

Results include facets for filtering by brand, price range, color, and other attributes.

Product Details

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
59
60
61
62
# GET /acp/products/:id
# Get detailed product information
 
curl -X GET "https://acp.acme.hyperfold.app/acp/products/prod_aero_x2?\
session_id=sess_abc123&\
buyer_context={"loyalty_tier":"gold"}"
 
# Response
{
  "product_id": "prod_aero_x2",
  "name": "AeroRun X2 Waterproof",
  "description": "Professional marathon shoe with Gore-Tex lining...",
  "brand": "AeroRun",
  "category": "footwear/running",
  "list_price": 179.99,
  "personalized_price": {
    "price": 162.00,
    "discount": "10%",
    "reason": "Gold member pricing"
  },
  "negotiable": true,
  "negotiation_hints": {
    "suggested_offer": 150.00,
    "likely_acceptance_range": [145, 165]
  },
  "attributes": {
    "material": "Gore-Tex, EVA foam",
    "weight": "280g",
    "waterproof_rating": "IPX5",
    "heel_drop": "8mm"
  },
  "variants": [
    {
      "id": "var_blue_10",
      "size": "10",
      "color": "blue",
      "sku": "AERO-X2-BLU-10",
      "in_stock": true,
      "quantity": 15
    }
  ],
  "images": [
    {"url": "https://cdn.acme.com/aero-x2-main.jpg", "position": 1},
    {"url": "https://cdn.acme.com/aero-x2-side.jpg", "position": 2},
    {"url": "https://cdn.acme.com/aero-x2-sole.jpg", "position": 3}
  ],
  "reviews": {
    "average_rating": 4.7,
    "count": 234,
    "summary": "Highly rated for comfort and waterproofing"
  },
  "shipping": {
    "free_shipping": false,
    "free_shipping_threshold": 75.00,
    "estimated_delivery": "2-3 business days"
  },
  "returns": {
    "allowed": true,
    "window_days": 30,
    "conditions": "Unworn, original packaging"
  }
}

Availability

Check real-time inventory and shipping options:

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
# POST /acp/availability
# Check real-time availability
 
curl -X POST https://acp.acme.hyperfold.app/acp/availability \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"product_id": "prod_aero_x2", "variant_id": "var_blue_10", "quantity": 2},
      {"product_id": "prod_socks_wp", "variant_id": "var_m", "quantity": 3}
    ],
    "shipping_address": {
      "postal_code": "94102",
      "country": "US"
    }
  }'
 
# Response
{
  "available": true,
  "items": [
    {
      "product_id": "prod_aero_x2",
      "variant_id": "var_blue_10",
      "requested_quantity": 2,
      "available_quantity": 15,
      "status": "in_stock",
      "warehouse": "Los Angeles, CA",
      "shipping_estimate": {
        "method": "standard",
        "days": "2-3",
        "cost": 0.00
      }
    },
    {
      "product_id": "prod_socks_wp",
      "variant_id": "var_m",
      "requested_quantity": 3,
      "available_quantity": 50,
      "status": "in_stock",
      "warehouse": "Los Angeles, CA",
      "shipping_estimate": {
        "method": "standard",
        "days": "2-3",
        "cost": 0.00
      }
    }
  ],
  "shipping_options": [
    {"method": "standard", "cost": 0.00, "days": "2-3"},
    {"method": "express", "cost": 12.99, "days": "1-2"},
    {"method": "overnight", "cost": 24.99, "days": "1"}
  ],
  "total_shipping": 0.00,
  "free_shipping_qualified": true
}
Ready to negotiate? See the ACP Commerce API for quotes and checkout.