Contracts after orientation
API Reference for implementers
Use this page after you know your path. Buyer-side agents start with REST/OpenAPI, A2A hosts discover the Agent Card, skill hosts install SKILL.md, and merchant agents use the registry plus proposal contracts.
How to use this page
Each section is a different integration surface. Typical order:
- OpenAPI — quick-start with `GET /v1/recommend`, or move deeper into `/v1/intents`, `/v1/proposals`, `/v1/match`, and `/v1/match-tokens`. Production API calls use Bearer API keys; copy-paste snippets live on Connect.
- Agent Card — point your A2A or discovery client at /.well-known/agent-card.json so capabilities stay aligned with this gateway.
- SKILL.md — for Claude / OpenClaw-style hosts, run the one-line installer on Connect; the skill maps natural language into recommend / card / showcase calls.
- Intent matching (v0.2) — merchant agents register, submit proposals, demand agents create match sessions, and accepted proposals mint match tokens. Event and object shapes are in the protocol docs below.
OpenAPI 3.0
Canonical REST contract for this gateway. The raw specification lives at /openapi.json — the same manifest consumed by ChatGPT custom GPTs and the Gemini extension.
SellToAI Gateway
Turn shopper intent into merchant-backed recommendations with proof, attribution-tracking buy links, and outcome feedback. Each returned card carries a path-bound buy link that MUST be passed to the user verbatim.
Browser playground & integration guides: https://selltoai.ai/ — try the API live, copy ready-made snippets for OpenClaw / Cursor / Claude Code / ChatGPT / Gemini / Codex / Hermes.
recommend
Recommendation and discovery endpoints. Production clients use Developer API keys; portal demo channels remain open.
GET
/v1/recommend
Recommend product cards by natural-language intent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
intent |
query |
yes | string |
User's natural-language intent. e.g. "gift for my 3yo nephew". |
limit |
query |
no | integer |
— |
region |
query |
no | string |
ISO country code (US, UK, ...) |
channel |
query |
no | string |
Channel hint (openclaw|cursor|gemini|chatgpt|hermes|...) |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"intent": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"count": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rec_id": {
"type": "string",
"description": "Globally unique recommendation id; primary key for attribution."
},
"product": {
"$ref": "#/components/schemas/Product"
},
"hero_pitch": {
"$ref": "#/components/schemas/HeroPitch"
},
"selection_story": {
"$ref": "#/components/schemas/SelectionStory"
},
"videos": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
},
"cta": {
"$ref": "#/components/schemas/Cta"
},
"compliance": {
"type": "object",
"properties": {
"region_allow": {
"$ref": "(max depth)"
},
"risk_level": {
"$ref": "(max depth)"
}
}
},
"generated_at": {
"type": "string",
"format": "date-time"
},
"channel": {
"type": "string",
"nullable": true
}
},
"required": [
"rec_id",
"product",
"hero_pitch",
"selection_story",
"videos",
"cta",
"generated_at"
]
}
},
"proposals": {
"type": "array",
"items": {
"type": "object"
}
},
"proposal_count": {
"type": "integer"
},
"match_session_id": {
"type": "string"
},
"shopper_guide": {
"type": "string",
"description": "Warm, human-facing copy from the shopper agent (Gemini); explains how picks relate to the user's intent."
},
"note": {
"type": "string",
"description": "Optional machine hint e.g. intent_plus_trending, trending_suggested.",
"nullable": true
},
"match_tier": {
"type": "string",
"description": "raw_substring | strict | narrow | fuzzy | broadened | none — how intent rows were retrieved before trending fill."
},
"intent_source": {
"type": "string"
},
"resolved_keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"resolved_categories": {
"type": "array",
"items": {
"type": "string"
}
},
"retrieval": {
"type": "object",
"properties": {
"intent_hits": {
"type": "integer"
},
"trending_fill": {
"type": "integer"
}
}
},
"generated_at": {
"type": "string",
"format": "date-time"
}
}
} |
503 | Recommendation service is temporarily unavailable. Retry later or contact SellToAI support if the issue persists. Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
card
Hydrate or look up a previously generated PCD.
GET
/v1/cards/{recId}
Look up a previously generated PCD by recId
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
recId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"rec_id": {
"type": "string",
"description": "Globally unique recommendation id; primary key for attribution."
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"brand": {
"type": "string",
"nullable": true
},
"price_usd": {
"type": "number",
"nullable": true
},
"original_price_usd": {
"type": "number",
"nullable": true
},
"discount_label": {
"type": "string",
"nullable": true
},
"main_image": {
"type": "string",
"nullable": true
},
"gallery": {
"type": "array",
"items": {
"type": "string"
}
},
"category_l1": {
"type": "string",
"nullable": true
},
"category_l2": {
"type": "string",
"nullable": true
}
}
},
"hero_pitch": {
"type": "object",
"properties": {
"one_liner": {
"type": "string"
},
"why_it_wins_on_tiktok": {
"type": "string"
},
"key_benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"icon": {
"$ref": "(max depth)"
},
"title": {
"$ref": "(max depth)"
},
"desc": {
"$ref": "(max depth)"
}
}
}
},
"target_audience": {
"type": "object",
"properties": {
"persona": {
"type": "string"
},
"age": {
"type": "string"
},
"region": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
}
}
}
}
},
"selection_story": {
"type": "object",
"properties": {
"headline": {
"type": "string"
},
"bullets": {
"type": "array",
"items": {
"type": "string"
}
},
"moras_score": {
"type": "number"
}
}
},
"videos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"task_id": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"username": {
"$ref": "(max depth)"
},
"display_name": {
"$ref": "(max depth)"
},
"avatar": {
"$ref": "(max depth)"
},
"followers": {
"$ref": "(max depth)"
}
}
},
"thumbnail": {
"type": "string",
"nullable": true
},
"video_url": {
"type": "string",
"nullable": true
},
"duration_s": {
"type": "integer"
},
"gmv_usd": {
"type": "number"
},
"orders": {
"type": "integer"
},
"views": {
"type": "integer"
},
"conversion_score": {
"type": "number"
},
"tiktok_video_url": {
"type": "string",
"nullable": true
}
}
}
},
"cta": {
"type": "object",
"properties": {
"primary": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"url": {
"type": "string",
"description": "MUST be passed to user verbatim — carries attribution rec_id."
}
}
},
"secondary": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"url": {
"type": "string"
}
}
}
}
},
"compliance": {
"type": "object",
"properties": {
"region_allow": {
"type": "array",
"items": {
"type": "string"
}
},
"risk_level": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
}
}
},
"generated_at": {
"type": "string",
"format": "date-time"
},
"channel": {
"type": "string",
"nullable": true
}
},
"required": [
"rec_id",
"product",
"hero_pitch",
"selection_story",
"videos",
"cta",
"generated_at"
],
"description": "Product Card Document — the atomic recommendation unit."
} |
404 | not found |
GET
/v1/products/{productId}/card
Build a fresh PCD for a known product id
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
productId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"rec_id": {
"type": "string",
"description": "Globally unique recommendation id; primary key for attribution."
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"brand": {
"type": "string",
"nullable": true
},
"price_usd": {
"type": "number",
"nullable": true
},
"original_price_usd": {
"type": "number",
"nullable": true
},
"discount_label": {
"type": "string",
"nullable": true
},
"main_image": {
"type": "string",
"nullable": true
},
"gallery": {
"type": "array",
"items": {
"type": "string"
}
},
"category_l1": {
"type": "string",
"nullable": true
},
"category_l2": {
"type": "string",
"nullable": true
}
}
},
"hero_pitch": {
"type": "object",
"properties": {
"one_liner": {
"type": "string"
},
"why_it_wins_on_tiktok": {
"type": "string"
},
"key_benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"icon": {
"$ref": "(max depth)"
},
"title": {
"$ref": "(max depth)"
},
"desc": {
"$ref": "(max depth)"
}
}
}
},
"target_audience": {
"type": "object",
"properties": {
"persona": {
"type": "string"
},
"age": {
"type": "string"
},
"region": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
}
}
}
}
},
"selection_story": {
"type": "object",
"properties": {
"headline": {
"type": "string"
},
"bullets": {
"type": "array",
"items": {
"type": "string"
}
},
"moras_score": {
"type": "number"
}
}
},
"videos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"task_id": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"username": {
"$ref": "(max depth)"
},
"display_name": {
"$ref": "(max depth)"
},
"avatar": {
"$ref": "(max depth)"
},
"followers": {
"$ref": "(max depth)"
}
}
},
"thumbnail": {
"type": "string",
"nullable": true
},
"video_url": {
"type": "string",
"nullable": true
},
"duration_s": {
"type": "integer"
},
"gmv_usd": {
"type": "number"
},
"orders": {
"type": "integer"
},
"views": {
"type": "integer"
},
"conversion_score": {
"type": "number"
},
"tiktok_video_url": {
"type": "string",
"nullable": true
}
}
}
},
"cta": {
"type": "object",
"properties": {
"primary": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"url": {
"type": "string",
"description": "MUST be passed to user verbatim — carries attribution rec_id."
}
}
},
"secondary": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"url": {
"type": "string"
}
}
}
}
},
"compliance": {
"type": "object",
"properties": {
"region_allow": {
"type": "array",
"items": {
"type": "string"
}
},
"risk_level": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
}
}
},
"generated_at": {
"type": "string",
"format": "date-time"
},
"channel": {
"type": "string",
"nullable": true
}
},
"required": [
"rec_id",
"product",
"hero_pitch",
"selection_story",
"videos",
"cta",
"generated_at"
],
"description": "Product Card Document — the atomic recommendation unit."
} |
creator
Browse a creator's showcase.
GET
/v1/creators/{username}/showcase
Top products this creator has produced winning videos for
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
username |
path |
yes | string |
— |
limit |
query |
no | integer |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"count": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rec_id": {
"type": "string",
"description": "Globally unique recommendation id; primary key for attribution."
},
"product": {
"$ref": "#/components/schemas/Product"
},
"hero_pitch": {
"$ref": "#/components/schemas/HeroPitch"
},
"selection_story": {
"$ref": "#/components/schemas/SelectionStory"
},
"videos": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
},
"cta": {
"$ref": "#/components/schemas/Cta"
},
"compliance": {
"type": "object",
"properties": {
"region_allow": {
"$ref": "(max depth)"
},
"risk_level": {
"$ref": "(max depth)"
}
}
},
"generated_at": {
"type": "string",
"format": "date-time"
},
"channel": {
"type": "string",
"nullable": true
}
},
"required": [
"rec_id",
"product",
"hero_pitch",
"selection_story",
"videos",
"cta",
"generated_at"
]
}
}
}
} |
intent
First-class intent objects for true A2A commerce flows.
POST
/v1/intent-mandates/sign
Sign a commerce intent mandate (RSA-SHA256 over canonical payload)
Auth
Details
Returns a signed Intent Mandate for bounded checkout or payment authorization flows when this capability is enabled for your integration.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | Signed mandate Body schema — application/json {
"type": "object"
} |
400 | invalid_body |
503 | Intent mandate signing is temporarily unavailable for this integration. |
POST
/v1/intents
Create a first-class intent
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | created Body schema — application/json · {
"type": "object",
"properties": {
"intent": {
"type": "object",
"properties": {
"intent_id": {
"type": "string"
},
"raw_query": {
"type": "string"
},
"normalized_query": {
"type": "string",
"nullable": true
},
"intent_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"target_audience": {
"type": "string",
"nullable": true
},
"budget_range": {
"type": "object",
"nullable": true
},
"region": {
"type": "string",
"nullable": true
},
"constraints": {
"type": "array",
"items": {
"type": "string"
}
},
"source_channel": {
"type": "string",
"nullable": true
},
"resolution_source": {
"type": "string",
"nullable": true
},
"resolution_summary": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"time_window": {
"type": "object",
"description": "Purchase deadline/urgency window used by agentic commerce workflows.",
"nullable": true
},
"asset_refs": {
"type": "array",
"items": {
"type": "object"
}
},
"attribution_chain": {
"type": "array",
"items": {
"type": "object"
}
},
"workflow": {
"type": "object",
"description": "Skill/MCP/A2A execution context for replay and governance."
},
"experience_context": {
"type": "object",
"description": "Experience intent context: scene, self_context, desired_feeling, visual constraints and confirmation goal."
}
}
}
}
} |
400 | missing_fields |
GET
/v1/intents/{intentId}
Fetch an intent by id
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
intentId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"intent": {
"type": "object",
"properties": {
"intent_id": {
"type": "string"
},
"raw_query": {
"type": "string"
},
"normalized_query": {
"type": "string",
"nullable": true
},
"intent_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"target_audience": {
"type": "string",
"nullable": true
},
"budget_range": {
"type": "object",
"nullable": true
},
"region": {
"type": "string",
"nullable": true
},
"constraints": {
"type": "array",
"items": {
"type": "string"
}
},
"source_channel": {
"type": "string",
"nullable": true
},
"resolution_source": {
"type": "string",
"nullable": true
},
"resolution_summary": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"time_window": {
"type": "object",
"description": "Purchase deadline/urgency window used by agentic commerce workflows.",
"nullable": true
},
"asset_refs": {
"type": "array",
"items": {
"type": "object"
}
},
"attribution_chain": {
"type": "array",
"items": {
"type": "object"
}
},
"workflow": {
"type": "object",
"description": "Skill/MCP/A2A execution context for replay and governance."
},
"experience_context": {
"type": "object",
"description": "Experience intent context: scene, self_context, desired_feeling, visual constraints and confirmation goal."
}
}
}
}
} |
404 | intent_not_found |
GET
/v1/intents/{intentId}/proposals
List proposals attached to an intent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
intentId |
path |
yes | string |
— |
include_expired |
query |
no | boolean |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"intent_id": {
"type": "string"
},
"count": {
"type": "integer"
},
"proposals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"proposal_id": {
"type": "string"
},
"merchant_agent_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"product_id": {
"type": "integer"
},
"offer_title": {
"type": "string"
},
"price": {
"type": "number",
"nullable": true
},
"inventory_status": {
"type": "string"
},
"shipping_commitment": {
"type": "object"
},
"commission_plan": {
"type": "object"
},
"service_terms": {
"type": "object"
},
"evidence": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true
},
"proposal_score_inputs": {
"type": "object"
},
"product_snapshot": {
"type": "object",
"nullable": true
},
"metadata": {
"type": "object"
},
"provenance": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"asset_refs": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
},
"trust_score": {
"type": "object",
"description": "Normalized trust/risk score and basis used for ranking/audit."
},
"attribution_chain": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
},
"proposal_state": {
"type": "string",
"description": "Commerce proposal lifecycle state.",
"enum": [
"draft",
"quoted",
"pending_confirmation",
"accepted",
"settled",
"expired"
]
},
"workflow": {
"type": "object",
"description": "Skill/MCP/A2A execution context for replay and governance."
},
"experience_preview": {
"type": "object",
"description": "Generated or referenced preview asset, scene preview and remixable dimensions."
},
"experience_card": {
"$ref": "#/components/schemas/ExperienceCard"
}
}
}
}
}
} |
404 | intent_not_found |
proposal
Merchant proposals attached to an intent.
POST
/v1/proposals
Submit a merchant proposal
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | created Body schema — application/json · {
"type": "object",
"properties": {
"proposal": {
"type": "object",
"properties": {
"proposal_id": {
"type": "string"
},
"merchant_agent_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"product_id": {
"type": "integer"
},
"offer_title": {
"type": "string"
},
"price": {
"type": "number",
"nullable": true
},
"inventory_status": {
"type": "string"
},
"shipping_commitment": {
"type": "object"
},
"commission_plan": {
"type": "object"
},
"service_terms": {
"type": "object"
},
"evidence": {
"type": "array",
"items": {
"type": "object"
}
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true
},
"proposal_score_inputs": {
"type": "object"
},
"product_snapshot": {
"type": "object",
"nullable": true
},
"metadata": {
"type": "object"
},
"provenance": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"asset_refs": {
"type": "array",
"items": {
"type": "object"
}
},
"trust_score": {
"type": "object",
"description": "Normalized trust/risk score and basis used for ranking/audit."
},
"attribution_chain": {
"type": "array",
"items": {
"type": "object"
}
},
"proposal_state": {
"type": "string",
"description": "Commerce proposal lifecycle state.",
"enum": [
"draft",
"quoted",
"pending_confirmation",
"accepted",
"settled",
"expired"
]
},
"workflow": {
"type": "object",
"description": "Skill/MCP/A2A execution context for replay and governance."
},
"experience_preview": {
"type": "object",
"description": "Generated or referenced preview asset, scene preview and remixable dimensions."
},
"experience_card": {
"type": "object",
"properties": {
"experience_id": {
"$ref": "(max depth)"
},
"intent_id": {
"$ref": "(max depth)"
},
"proposal_id": {
"$ref": "(max depth)"
},
"scene": {
"$ref": "(max depth)"
},
"preview": {
"$ref": "(max depth)"
},
"products": {
"$ref": "(max depth)"
},
"creator_evidence": {
"$ref": "(max depth)"
},
"why_it_fits_you": {
"$ref": "(max depth)"
},
"remix_actions": {
"$ref": "(max depth)"
},
"cta": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
401 | missing registration token |
403 | invalid registration token |
404 | intent_not_found or merchant_not_found |
GET
/v1/proposals/{proposalId}
Fetch a proposal by id
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
proposalId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"proposal": {
"type": "object",
"properties": {
"proposal_id": {
"type": "string"
},
"merchant_agent_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"product_id": {
"type": "integer"
},
"offer_title": {
"type": "string"
},
"price": {
"type": "number",
"nullable": true
},
"inventory_status": {
"type": "string"
},
"shipping_commitment": {
"type": "object"
},
"commission_plan": {
"type": "object"
},
"service_terms": {
"type": "object"
},
"evidence": {
"type": "array",
"items": {
"type": "object"
}
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true
},
"proposal_score_inputs": {
"type": "object"
},
"product_snapshot": {
"type": "object",
"nullable": true
},
"metadata": {
"type": "object"
},
"provenance": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"asset_refs": {
"type": "array",
"items": {
"type": "object"
}
},
"trust_score": {
"type": "object",
"description": "Normalized trust/risk score and basis used for ranking/audit."
},
"attribution_chain": {
"type": "array",
"items": {
"type": "object"
}
},
"proposal_state": {
"type": "string",
"description": "Commerce proposal lifecycle state.",
"enum": [
"draft",
"quoted",
"pending_confirmation",
"accepted",
"settled",
"expired"
]
},
"workflow": {
"type": "object",
"description": "Skill/MCP/A2A execution context for replay and governance."
},
"experience_preview": {
"type": "object",
"description": "Generated or referenced preview asset, scene preview and remixable dimensions."
},
"experience_card": {
"type": "object",
"properties": {
"experience_id": {
"$ref": "(max depth)"
},
"intent_id": {
"$ref": "(max depth)"
},
"proposal_id": {
"$ref": "(max depth)"
},
"scene": {
"$ref": "(max depth)"
},
"preview": {
"$ref": "(max depth)"
},
"products": {
"$ref": "(max depth)"
},
"creator_evidence": {
"$ref": "(max depth)"
},
"why_it_fits_you": {
"$ref": "(max depth)"
},
"remix_actions": {
"$ref": "(max depth)"
},
"cta": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
404 | proposal_not_found |
match
Rank proposals into match sessions and mint match tokens.
POST
/v1/match
Create a match session from an intent and proposals
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | created Body schema — application/json · {
"type": "object",
"properties": {
"match_session": {
"type": "object",
"properties": {
"match_session_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"best_proposal_id": {
"type": "string",
"nullable": true
},
"ranked_proposals": {
"type": "array",
"items": {
"type": "object"
}
},
"summary": {
"type": "object"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
400 | missing_fields |
404 | intent_not_found or proposal_not_found |
GET
/v1/match/{matchSessionId}
Fetch a rendered match session
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
matchSessionId |
path |
yes | string |
— |
limit |
query |
no | integer |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"match_session": {
"type": "object",
"properties": {
"match_session_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"best_proposal_id": {
"type": "string",
"nullable": true
},
"ranked_proposals": {
"type": "array",
"items": {
"type": "object"
}
},
"summary": {
"type": "object"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
},
"ranked_proposals": {
"type": "array",
"items": {
"type": "object"
}
},
"match_tokens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"match_token_id": {
"type": "string"
},
"match_session_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"proposal_id": {
"type": "string"
},
"acceptance_state": {
"type": "string"
},
"intent_snapshot": {
"type": "object"
},
"proposal_snapshot": {
"type": "object"
},
"ranking_snapshot": {
"type": "object"
},
"trace_ids": {
"type": "object"
},
"issued_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rec_id": {
"type": "string",
"description": "Globally unique recommendation id; primary key for attribution."
},
"product": {
"$ref": "#/components/schemas/Product"
},
"hero_pitch": {
"$ref": "#/components/schemas/HeroPitch"
},
"selection_story": {
"$ref": "#/components/schemas/SelectionStory"
},
"videos": {
"type": "array",
"items": {
"$ref": "(max depth)"
}
},
"cta": {
"$ref": "#/components/schemas/Cta"
},
"compliance": {
"type": "object",
"properties": {
"region_allow": {
"$ref": "(max depth)"
},
"risk_level": {
"$ref": "(max depth)"
}
}
},
"generated_at": {
"type": "string",
"format": "date-time"
},
"channel": {
"type": "string",
"nullable": true
}
},
"required": [
"rec_id",
"product",
"hero_pitch",
"selection_story",
"videos",
"cta",
"generated_at"
]
}
}
}
} |
404 | match_not_found |
POST
/v1/match/{matchSessionId}/accept
Accept a ranked proposal and mint or confirm the match token
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
matchSessionId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"match_token": {
"type": "object",
"properties": {
"match_token_id": {
"type": "string"
},
"match_session_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"proposal_id": {
"type": "string"
},
"acceptance_state": {
"type": "string"
},
"intent_snapshot": {
"type": "object"
},
"proposal_snapshot": {
"type": "object"
},
"ranking_snapshot": {
"type": "object"
},
"trace_ids": {
"type": "object"
},
"issued_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
404 | match_not_found |
GET
/v1/match-tokens/{matchTokenId}
Fetch a match token by id
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
matchTokenId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"match_token": {
"type": "object",
"properties": {
"match_token_id": {
"type": "string"
},
"match_session_id": {
"type": "string"
},
"intent_id": {
"type": "string"
},
"proposal_id": {
"type": "string"
},
"acceptance_state": {
"type": "string"
},
"intent_snapshot": {
"type": "object"
},
"proposal_snapshot": {
"type": "object"
},
"ranking_snapshot": {
"type": "object"
},
"trace_ids": {
"type": "object"
},
"issued_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
404 | match_token_not_found |
merchant
Merchant / supply-side Agent registry and lifecycle endpoints.
POST
/v1/merchant/register
Register a merchant Agent (intent-matching v0.1)
Auth
Details
Registers a merchant agent endpoint, subscription tags, capabilities, and routing scope for SellToAI (K2Lab). Registration is persisted and token-protected; merchants can heartbeat, health-check, receive Intent.Surge dispatches, and submit proposals. See /docs/INTENT_MATCHING_PROTOCOL.md on this gateway.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"created": {
"type": "boolean"
},
"merchant_id": {
"type": "string"
},
"registration_token": {
"type": "string",
"description": "Secret token used for heartbeat, updates, deactivation, and proposal submission."
},
"merchant": {
"type": "object",
"properties": {
"merchant_id": {
"type": "string"
},
"agent_endpoint": {
"type": "string"
},
"subscription_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"category_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"inventory_scope": {
"type": "array",
"items": {
"type": "object"
}
},
"protocol_version": {
"type": "string",
"nullable": true
},
"a2a_capabilities": {
"type": "object"
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"workflow_context": {
"type": "object",
"properties": {
"origin_workflow": {
"$ref": "(max depth)"
},
"accepted_intent_shapes": {
"$ref": "(max depth)"
},
"required_context": {
"$ref": "(max depth)"
},
"proposal_response_sla_seconds": {
"$ref": "(max depth)"
},
"checkout_modes": {
"$ref": "(max depth)"
}
}
},
"trust_evidence_policy": {
"type": "object",
"properties": {
"community_proof_required": {
"$ref": "(max depth)"
},
"accepted_sources": {
"$ref": "(max depth)"
},
"min_consensus_score": {
"$ref": "(max depth)"
},
"contradiction_handling": {
"$ref": "(max depth)"
}
}
},
"agent_ready_profile": {
"type": "object",
"properties": {
"destination_strategy": {
"$ref": "(max depth)"
},
"proposal_contract": {
"$ref": "(max depth)"
},
"attribution_mode": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
400 | missing_fields — merchant_id and agent_endpoint required |
GET
/v1/merchant/{merchantId}
Fetch a registered merchant Agent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
merchantId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string",
"nullable": true
},
"merchant": {
"type": "object",
"properties": {
"merchant_id": {
"type": "string"
},
"agent_endpoint": {
"type": "string"
},
"subscription_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"category_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"inventory_scope": {
"type": "array",
"items": {
"type": "object"
}
},
"protocol_version": {
"type": "string",
"nullable": true
},
"a2a_capabilities": {
"type": "object"
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"workflow_context": {
"type": "object",
"properties": {
"origin_workflow": {
"$ref": "(max depth)"
},
"accepted_intent_shapes": {
"$ref": "(max depth)"
},
"required_context": {
"$ref": "(max depth)"
},
"proposal_response_sla_seconds": {
"$ref": "(max depth)"
},
"checkout_modes": {
"$ref": "(max depth)"
}
}
},
"trust_evidence_policy": {
"type": "object",
"properties": {
"community_proof_required": {
"$ref": "(max depth)"
},
"accepted_sources": {
"$ref": "(max depth)"
},
"min_consensus_score": {
"$ref": "(max depth)"
},
"contradiction_handling": {
"$ref": "(max depth)"
}
}
},
"agent_ready_profile": {
"type": "object",
"properties": {
"destination_strategy": {
"$ref": "(max depth)"
},
"proposal_contract": {
"$ref": "(max depth)"
},
"attribution_mode": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
404 | merchant_not_found |
GET
/v1/merchant/{merchantId}/health
Probe merchant Agent health
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
merchantId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | merchant healthy |
503 | merchant unhealthy or unreachable |
POST
/v1/merchant/heartbeat
Heartbeat a merchant Agent
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string",
"nullable": true
},
"merchant": {
"type": "object",
"properties": {
"merchant_id": {
"type": "string"
},
"agent_endpoint": {
"type": "string"
},
"subscription_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"category_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"inventory_scope": {
"type": "array",
"items": {
"type": "object"
}
},
"protocol_version": {
"type": "string",
"nullable": true
},
"a2a_capabilities": {
"type": "object"
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"workflow_context": {
"type": "object",
"properties": {
"origin_workflow": {
"$ref": "(max depth)"
},
"accepted_intent_shapes": {
"$ref": "(max depth)"
},
"required_context": {
"$ref": "(max depth)"
},
"proposal_response_sla_seconds": {
"$ref": "(max depth)"
},
"checkout_modes": {
"$ref": "(max depth)"
}
}
},
"trust_evidence_policy": {
"type": "object",
"properties": {
"community_proof_required": {
"$ref": "(max depth)"
},
"accepted_sources": {
"$ref": "(max depth)"
},
"min_consensus_score": {
"$ref": "(max depth)"
},
"contradiction_handling": {
"$ref": "(max depth)"
}
}
},
"agent_ready_profile": {
"type": "object",
"properties": {
"destination_strategy": {
"$ref": "(max depth)"
},
"proposal_contract": {
"$ref": "(max depth)"
},
"attribution_mode": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
401 | missing registration token |
403 | invalid registration token |
POST
/v1/merchant/{merchantId}/deactivate
Deactivate a merchant Agent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
merchantId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string",
"nullable": true
},
"merchant": {
"type": "object",
"properties": {
"merchant_id": {
"type": "string"
},
"agent_endpoint": {
"type": "string"
},
"subscription_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"category_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"inventory_scope": {
"type": "array",
"items": {
"type": "object"
}
},
"protocol_version": {
"type": "string",
"nullable": true
},
"a2a_capabilities": {
"type": "object"
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"workflow_context": {
"type": "object",
"properties": {
"origin_workflow": {
"$ref": "(max depth)"
},
"accepted_intent_shapes": {
"$ref": "(max depth)"
},
"required_context": {
"$ref": "(max depth)"
},
"proposal_response_sla_seconds": {
"$ref": "(max depth)"
},
"checkout_modes": {
"$ref": "(max depth)"
}
}
},
"trust_evidence_policy": {
"type": "object",
"properties": {
"community_proof_required": {
"$ref": "(max depth)"
},
"accepted_sources": {
"$ref": "(max depth)"
},
"min_consensus_score": {
"$ref": "(max depth)"
},
"contradiction_handling": {
"$ref": "(max depth)"
}
}
},
"agent_ready_profile": {
"type": "object",
"properties": {
"destination_strategy": {
"$ref": "(max depth)"
},
"proposal_contract": {
"$ref": "(max depth)"
},
"attribution_mode": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
401 | missing registration token |
403 | invalid registration token |
GET
/v1/merchant/{merchantId}/agent-readiness
Assess whether a merchant is ready for embedded AI shopping workflows
Auth
Details
Scores a registered merchant against the Agent-ready commerce checklist: workflow context, committed proposal contract, trust evidence policy, and MatchToken attribution. This translates the AI-commerce shift from destination apps to embedded workflows into a concrete supply-side gate.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
merchantId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"merchant_id": {
"type": "string"
},
"score": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"summary": {
"type": "object",
"properties": {
"ready_for_embedded_workflows": {
"type": "boolean"
},
"insight": {
"type": "string"
},
"next_upgrade": {
"type": "string"
}
}
},
"checks": {
"type": "object"
},
"merchant": {
"type": "object",
"properties": {
"merchant_id": {
"type": "string"
},
"agent_endpoint": {
"type": "string"
},
"subscription_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"category_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"inventory_scope": {
"type": "array",
"items": {
"type": "object"
}
},
"protocol_version": {
"type": "string",
"nullable": true
},
"a2a_capabilities": {
"type": "object"
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"workflow_context": {
"type": "object",
"properties": {
"origin_workflow": {
"$ref": "(max depth)"
},
"accepted_intent_shapes": {
"$ref": "(max depth)"
},
"required_context": {
"$ref": "(max depth)"
},
"proposal_response_sla_seconds": {
"$ref": "(max depth)"
},
"checkout_modes": {
"$ref": "(max depth)"
}
}
},
"trust_evidence_policy": {
"type": "object",
"properties": {
"community_proof_required": {
"$ref": "(max depth)"
},
"accepted_sources": {
"$ref": "(max depth)"
},
"min_consensus_score": {
"$ref": "(max depth)"
},
"contradiction_handling": {
"$ref": "(max depth)"
}
}
},
"agent_ready_profile": {
"type": "object",
"properties": {
"destination_strategy": {
"$ref": "(max depth)"
},
"proposal_contract": {
"$ref": "(max depth)"
},
"attribution_mode": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
404 | merchant_not_found |
GET
/v1/merchant/dispatch-queue
List merchant dispatch queue and DLQ deliveries
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Supply-Key |
header |
yes | string |
Supply/admin key for operational reporting and replay endpoints. |
state |
query |
no | string |
— |
merchant_id |
query |
no | string |
— |
intent_id |
query |
no | string |
— |
Responses
| Code | Description |
|---|---|
200 | Queue summary and deliveries |
401 | Invalid or missing supply key |
POST
/v1/merchant/dispatch-queue/retry
Retry one DLQ delivery or replay all DLQ deliveries
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Supply-Key |
header |
yes | string |
Supply/admin key for operational reporting and replay endpoints. |
Responses
| Code | Description |
|---|---|
200 | Retry results |
401 | Invalid or missing supply key |
GET
/v1/merchant/{merchantId}/sla
Get merchant SLA metrics from feedback events
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Supply-Key |
header |
yes | string |
Supply/admin key for operational reporting and replay endpoints. |
merchantId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | Merchant SLA summary |
401 | Invalid or missing supply key |
GET
/v1/merchant/{merchantId}/reputation
Recompute and return merchant reputation snapshot
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Supply-Key |
header |
yes | string |
Supply/admin key for operational reporting and replay endpoints. |
merchantId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | Merchant reputation snapshot |
401 | Invalid or missing supply key |
agents
General Commerce Agent registry: merchant, payment, logistics, creator, demand-side, and SellToAI / Moras core agents.
POST
/v1/agents/register
Register a Commerce Agent
Auth
Details
Registers any external commerce agent (merchant/payment/logistics/creator/demand) with protocol and capability declarations.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | Updated Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"created": {
"type": "boolean"
},
"agent_id": {
"type": "string"
},
"registration_token": {
"type": "string",
"description": "Secret token for heartbeat, updates and deactivation."
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
201 | Created Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"created": {
"type": "boolean"
},
"agent_id": {
"type": "string"
},
"registration_token": {
"type": "string",
"description": "Secret token for heartbeat, updates and deactivation."
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
400 | missing_fields |
POST
/v1/agents/import-card
Import an A2A Agent Card
Auth
Details
Imports an inline agent_card or fetches agent_card_url, maps skills/endpoints into a Commerce Agent capability profile, and registers it.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | Created Body schema — application/json · {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"created": {
"type": "boolean"
},
"agent_id": {
"type": "string"
},
"registration_token": {
"type": "string",
"description": "Secret token for heartbeat, updates and deactivation."
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
502 | agent_card_fetch_failed |
GET
/v1/agents
List Commerce Agents
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
agent_type |
query |
no | string |
— |
status |
query |
no | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"agents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
}
} |
GET
/v1/agents/{agentId}
Fetch a Commerce Agent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
agentId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json {
"type": "object",
"properties": {
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
404 | agent_not_found |
POST
/v1/agents/{agentId}/heartbeat
Heartbeat a Commerce Agent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
agentId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
401 | X-Agent-Token required |
POST
/v1/agents/{agentId}/deactivate
Deactivate a Commerce Agent
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
agentId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"agent_card_url": {
"type": "string",
"nullable": true
},
"protocols": {
"type": "array",
"items": {
"type": "string"
}
},
"auth_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"capability_profile": {
"type": "object"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object"
},
"status": {
"type": "string"
},
"registered_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"deactivated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
report
Supply-side ROI reports (auth required).
GET
/v1/report/attribution
ROI report (supply side, requires X-Supply-Key)
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
days |
query |
no | integer |
— |
channel |
query |
no | string |
— |
product_id |
query |
no | string |
— |
Responses
| Code | Description |
|---|---|
200 | OK |
401 | unauthorized |
developer
Developer accounts, invite verification, API key management, and request logs.
POST
/v1/developers/register
Register a developer account
Details
Creates a password-based developer account and returns a console session token. API keys are created separately after invite verification.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | Developer account created; use developer_token for console management endpoints. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"developer": {
"type": "object",
"properties": {
"developer_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"contact_email": {
"type": "string"
},
"company": {
"type": "string",
"nullable": true
},
"website": {
"type": "string",
"nullable": true
},
"status": {
"type": "string"
},
"invite_verified_at": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"nullable": true
}
}
},
"developer_token": {
"type": "string",
"description": "Console session token for developer management endpoints."
},
"session": {
"type": "object",
"properties": {
"session_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"last_used_at": {
"type": "string",
"nullable": true
}
}
},
"invite_verified": {
"type": "boolean"
}
}
} |
400 | Invalid registration payload Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
409 | Developer account already exists for this email Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
GET
/v1/developers/me
Fetch the authenticated developer console profile
Auth
Details
Requires a developer_token from register or login, not an API key.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | Developer profile, console session, invite status, and API keys. Body schema — application/json {
"type": "object",
"properties": {
"developer": {
"type": "object",
"properties": {
"developer_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"contact_email": {
"type": "string"
},
"company": {
"type": "string",
"nullable": true
},
"website": {
"type": "string",
"nullable": true
},
"status": {
"type": "string"
},
"invite_verified_at": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"nullable": true
}
}
},
"session": {
"type": "object",
"properties": {
"session_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"last_used_at": {
"type": "string",
"nullable": true
}
}
},
"invite_verified": {
"type": "boolean"
},
"keys": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
},
"can_reveal": {
"type": "boolean"
}
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
GET
/v1/developers/keys
List API keys for the authenticated developer account
Auth
Details
Requires a developer_token from register or login.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | API keys. Body schema — application/json {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"invite_verified": {
"type": "boolean"
},
"keys": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
},
"can_reveal": {
"type": "boolean"
}
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
POST
/v1/developers/keys
Create a new API key after invite verification
Auth
Details
Requires a developer_token and a verified invite code. The full API key can be copied from the response and revealed later from the developer console.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | API key created. The full value can be copied or revealed from the developer console while encrypted key storage is available. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"api_key": {
"type": "string"
},
"key": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
},
"can_reveal": {
"type": "boolean"
}
}
},
"warning": {
"type": "string"
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
403 | Invite verification is required before creating API keys Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
POST
/v1/developers/keys/{keyId}/revoke
Disable an API key (deprecated; use DELETE /v1/developers/keys/{keyId})
Auth
Details
Requires a developer_token from register or login.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
keyId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | Key revoked. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"key": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
},
"can_reveal": {
"type": "boolean"
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
404 | API key not found Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
GET
/v1/developers/logs
List recent API request logs for the developer account
Auth
Details
Requires a developer_token from register or login.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
limit |
query |
no | integer |
— |
Responses
| Code | Description |
|---|---|
200 | Request logs. Body schema — application/json {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"request_id": {
"type": "string"
},
"key_id": {
"type": "string"
},
"channel": {
"type": "string",
"nullable": true
},
"method": {
"type": "string"
},
"path": {
"type": "string"
},
"status_code": {
"type": "integer"
},
"duration_ms": {
"type": "integer"
},
"created_at": {
"type": "string"
}
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
POST
/v1/developers/login
Log in to the developer console
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | Developer console session created. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"developer": {
"type": "object",
"properties": {
"developer_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"contact_email": {
"type": "string"
},
"company": {
"type": "string",
"nullable": true
},
"website": {
"type": "string",
"nullable": true
},
"status": {
"type": "string"
},
"invite_verified_at": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"nullable": true
}
}
},
"developer_token": {
"type": "string",
"description": "Console session token for developer management endpoints."
},
"session": {
"type": "object",
"properties": {
"session_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"last_used_at": {
"type": "string",
"nullable": true
}
}
},
"invite_verified": {
"type": "boolean"
}
}
} |
400 | Invalid login payload Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
401 | Invalid email or password Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
POST
/v1/developers/invite/verify
Verify a developer invite code
Auth
Details
Requires a developer_token. API key creation is blocked until invite verification succeeds.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | Invite verified. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"developer": {
"type": "object",
"properties": {
"developer_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"contact_email": {
"type": "string"
},
"company": {
"type": "string",
"nullable": true
},
"website": {
"type": "string",
"nullable": true
},
"status": {
"type": "string"
},
"invite_verified_at": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"nullable": true
}
}
},
"invite_verified": {
"type": "boolean"
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
403 | Invalid invite code Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
PATCH
/v1/developers/keys/{keyId}
Rename an API key
Auth
Details
Requires a developer_token from register or login. Updates the key label shown in the developer console.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
keyId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | API key label updated. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"key": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
},
"can_reveal": {
"type": "boolean"
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
404 | API key not found Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
DELETE
/v1/developers/keys/{keyId}
Delete an API key
Auth
Details
Requires a developer_token from register or login. Deleted keys stop authenticating immediately while the key record is retained for audit and request-log joins.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
keyId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | API key deleted and retained for audit. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"key": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
},
"can_reveal": {
"type": "boolean"
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
404 | API key not found Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
POST
/v1/developers/keys/{keyId}/reveal
Reveal and copy an API key
Auth
Details
Requires a developer_token from register or login. Returns the full API key for keys created after encrypted key storage was enabled.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
keyId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | Full API key returned. Body schema — application/json {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"api_key": {
"type": "string"
},
"key": {
"type": "object",
"properties": {
"key_id": {
"type": "string"
},
"developer_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"can_reveal": {
"type": "boolean"
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"deleted"
]
},
"last_used_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"nullable": true
},
"revoked_at": {
"type": "string",
"nullable": true
}
}
}
}
} |
401 | Missing or invalid developer session token Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
404 | API key not found Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
410 | Full key is unavailable for older hash-only keys Body schema — application/json {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
}
}
} |
commerce-proof
Outcome-backed creator video assets that external agents can use as commerce proof for proposal generation.
GET
/v1/proof-feed
List commerce proof assets, including automated community proof
Auth
Details
Returns outcome-backed shoppable video assets by default. Pass source=community to return query-scoped Reddit/community trust evidence with an automation plan; this avoids manual curation and avoids full Reddit crawling.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
limit |
query |
no | integer |
— |
source |
query |
no | string |
Use community/community-proof/reddit to return automated Community Proof assets. |
intent |
query |
no | string |
Shopping intent used to build scoped Reddit search import URLs. |
products |
query |
no | string |
Comma-separated product names used for exact product mention import. |
subreddits |
query |
no | string |
Comma-separated subreddit allowlist for bounded import; not recursive crawling. |
Responses
| Code | Description |
|---|---|
200 | Commerce or community proof feed Body schema — application/json {
"oneOf": [
{
"$ref": "#/components/schemas/CommerceProofFeedResponse"
},
{
"$ref": "#/components/schemas/CommunityProofFeedResponse"
}
]
} |
billing
Billing and settlement previews.
POST
/v1/billing/settlement-preview
Preview merchant billing/settlement from attributed orders and accepted matches
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Supply-Key |
header |
yes | string |
Supply/admin key for operational reporting and replay endpoints. |
Responses
| Code | Description |
|---|---|
200 | Billing preview |
400 | Missing merchant id |
401 | Invalid or missing supply key |
reconciliation
Order reconciliation controls.
POST
/v1/reconciliation/tiktok-affiliate/run
Run TikTok Affiliate order reconciliation
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Supply-Key |
header |
yes | string |
Supply/admin key for operational reporting and replay endpoints. |
Responses
| Code | Description |
|---|---|
200 | Reconciliation result |
401 | Invalid supply key |
checkout
Payment/checkout authorization against MatchToken credentials.
POST
/v1/match-tokens/{matchTokenId}/payment-authorization
Authorize checkout/payment against a verified MatchToken
Auth
Details
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
matchTokenId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | Payment is authorized |
409 | Token, proposal, amount, or acceptance state is not valid for payment |
experience-commerce
POST
/v1/decision-events
Record a proposal/experience decision feedback event
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | created Body schema — application/json · {
"type": "object",
"properties": {
"decision_event": {
"type": "object",
"properties": {
"feedback_id": {
"type": "string"
},
"event_type": {
"type": "string"
},
"intent_id": {
"type": "string",
"nullable": true
},
"proposal_id": {
"type": "string",
"nullable": true
},
"match_token_id": {
"type": "string",
"nullable": true
},
"payload": {
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
} |
400 | unsupported_decision_event |
POST
/v1/experience-feed
Prepare proactive ready-to-experience proposal shells
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
200 | OK Body schema — application/json · {
"type": "object",
"properties": {
"feed": {
"type": "object",
"properties": {
"feed_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"taste_profile": {
"type": "object"
},
"inspiration_refs": {
"type": "array",
"items": {
"type": "object"
}
},
"items": {
"type": "array",
"items": {
"type": "object"
}
},
"generated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
} |
commerce-runtime
POST
/v1/commerce-runtime
Run an auditable SellToAI Commerce Agent Runtime loop
Auth
Details
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | created Body schema — application/json · {
"type": "object",
"properties": {
"runtime": {
"type": "object",
"properties": {
"runtime_session": {
"type": "object",
"properties": {
"runtime_id": {
"$ref": "(max depth)"
},
"entry_agent_id": {
"$ref": "(max depth)"
},
"mode": {
"$ref": "(max depth)"
},
"stage": {
"$ref": "(max depth)"
},
"started_at": {
"$ref": "(max depth)"
}
}
},
"intent": {
"type": "object",
"properties": {
"intent_id": {
"$ref": "(max depth)"
},
"raw_query": {
"$ref": "(max depth)"
},
"normalized_query": {
"$ref": "(max depth)"
},
"intent_tags": {
"$ref": "(max depth)"
},
"target_audience": {
"$ref": "(max depth)"
},
"budget_range": {
"$ref": "(max depth)"
},
"region": {
"$ref": "(max depth)"
},
"constraints": {
"$ref": "(max depth)"
},
"source_channel": {
"$ref": "(max depth)"
},
"resolution_source": {
"$ref": "(max depth)"
},
"resolution_summary": {
"$ref": "(max depth)"
},
"metadata": {
"$ref": "(max depth)"
},
"created_at": {
"$ref": "(max depth)"
},
"updated_at": {
"$ref": "(max depth)"
},
"time_window": {
"$ref": "(max depth)"
},
"asset_refs": {
"$ref": "(max depth)"
},
"attribution_chain": {
"$ref": "(max depth)"
},
"workflow": {
"$ref": "(max depth)"
},
"experience_context": {
"$ref": "(max depth)"
}
}
},
"proposal": {
"type": "object",
"properties": {
"proposal_id": {
"$ref": "(max depth)"
},
"merchant_agent_id": {
"$ref": "(max depth)"
},
"intent_id": {
"$ref": "(max depth)"
},
"product_id": {
"$ref": "(max depth)"
},
"offer_title": {
"$ref": "(max depth)"
},
"price": {
"$ref": "(max depth)"
},
"inventory_status": {
"$ref": "(max depth)"
},
"shipping_commitment": {
"$ref": "(max depth)"
},
"commission_plan": {
"$ref": "(max depth)"
},
"service_terms": {
"$ref": "(max depth)"
},
"evidence": {
"$ref": "(max depth)"
},
"valid_until": {
"$ref": "(max depth)"
},
"proposal_score_inputs": {
"$ref": "(max depth)"
},
"product_snapshot": {
"$ref": "(max depth)"
},
"metadata": {
"$ref": "(max depth)"
},
"provenance": {
"$ref": "(max depth)"
},
"status": {
"$ref": "(max depth)"
},
"created_at": {
"$ref": "(max depth)"
},
"updated_at": {
"$ref": "(max depth)"
},
"asset_refs": {
"$ref": "(max depth)"
},
"trust_score": {
"$ref": "(max depth)"
},
"attribution_chain": {
"$ref": "(max depth)"
},
"proposal_state": {
"$ref": "(max depth)"
},
"workflow": {
"$ref": "(max depth)"
},
"experience_preview": {
"$ref": "(max depth)"
},
"experience_card": {
"$ref": "(max depth)"
}
}
},
"match_session": {
"type": "object",
"properties": {
"match_session_id": {
"$ref": "(max depth)"
},
"intent_id": {
"$ref": "(max depth)"
},
"best_proposal_id": {
"$ref": "(max depth)"
},
"ranked_proposals": {
"$ref": "(max depth)"
},
"summary": {
"$ref": "(max depth)"
},
"status": {
"$ref": "(max depth)"
},
"created_at": {
"$ref": "(max depth)"
},
"updated_at": {
"$ref": "(max depth)"
}
}
},
"match_token": {
"type": "object",
"properties": {
"match_token_id": {
"$ref": "(max depth)"
},
"match_session_id": {
"$ref": "(max depth)"
},
"intent_id": {
"$ref": "(max depth)"
},
"proposal_id": {
"$ref": "(max depth)"
},
"acceptance_state": {
"$ref": "(max depth)"
},
"intent_snapshot": {
"$ref": "(max depth)"
},
"proposal_snapshot": {
"$ref": "(max depth)"
},
"ranking_snapshot": {
"$ref": "(max depth)"
},
"trace_ids": {
"$ref": "(max depth)"
},
"issued_at": {
"$ref": "(max depth)"
},
"expires_at": {
"$ref": "(max depth)"
},
"accepted_at": {
"$ref": "(max depth)"
}
}
},
"agent_steps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentStep"
}
},
"commerce_budget": {
"type": "object",
"properties": {
"max_agent_iterations": {
"$ref": "(max depth)"
},
"max_merchant_queries": {
"$ref": "(max depth)"
},
"max_proposal_versions": {
"$ref": "(max depth)"
},
"require_user_confirmation_before_payment": {
"$ref": "(max depth)"
}
}
},
"commerce_memory_refs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommerceMemoryRef"
}
},
"skill_refs": {
"type": "array",
"items": {
"type": "string"
}
},
"runtime_trace": {
"type": "object",
"properties": {
"loop": {
"$ref": "(max depth)"
},
"current_step": {
"$ref": "(max depth)"
},
"audit_status": {
"$ref": "(max depth)"
}
}
}
}
}
}
} |
400 | missing_intent |
agentic-checkout
POST
/v1/agentic-checkout
Create an Agentic Checkout transaction plan
Auth
Details
Turns a buyer-agent intent and merchant proposal into an auditable intent→proposal→MatchToken→confirmation transaction plan. This is the SellToAI Agentic Commerce path: optimize for trusted successful transactions, not ad impressions.
Parameters
No parameters.
Responses
| Code | Description |
|---|---|
201 | Checkout created and waiting for explicit buyer confirmation Body schema — application/json {
"type": "object"
} |
400 | Invalid checkout request |
POST
/v1/agentic-checkout/{checkoutId}/confirm
Confirm an Agentic Checkout with MatchToken payment authorization
Auth
Details
Requires explicit buyer-agent consent, accepts the signed MatchToken, verifies proposal/amount/currency, and returns a merchant handoff receipt plus audit trail.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
checkoutId |
path |
yes | string |
— |
Responses
| Code | Description |
|---|---|
200 | Checkout confirmed and authorized for payment or merchant handoff Body schema — application/json {
"type": "object"
} |
409 | Consent, token, proposal, amount, or currency mismatch |
Developer API keys
Production API calls are designed to use `Authorization: Bearer <SellToAI API key>` so open docs do not become an unauthenticated compute surface.
Create a developer account, verify an invite code, then create API keys in the developer console. The gateway stores a hash for authentication and an encrypted copy for console reveal.
Auth quick start
- Register with `display_name`, `contact_email`, `password`, and basic company information, then log in to the developer console.
- Verify your invite code before creating API keys. New keys can be revealed and copied from the developer console while the encryption secret remains stable.
- Send API keys as `Authorization: Bearer MA2A.xxx` on `/v1/*` calls from apps, agents, MCP wrappers, or custom scripts.
curl -H 'Authorization: Bearer MA2A.xxx' '/v1/recommend?intent=desk+lamp&limit=3'
Stored only in this browser localStorage and used to render copy-paste snippets.
Commerce Agent Registry
The gateway now has a general external agent directory for merchant, payment, logistics, creator, demand-side, and SellToAI-core agents.
Use `/v1/agents/register`, `/v1/agents/import-card`, list/fetch, heartbeat, and deactivate endpoints when you need protocol and capability metadata beyond the legacy merchant registry.
Registry quick start
- Register with `agent_id`, `agent_type`, `endpoint`, supported protocols, auth methods, and a capability profile.
- Store the returned `registration_token`; send it as `X-Agent-Token` for heartbeat and lifecycle updates.
- Demand-side agents can discover available peers through `GET /v1/agents?agent_type=...` or the A2A/MCP discovery tools.
Intent matching & merchant agents
SellToAI now exposes the core objects required for true A-to-A commerce between demand-side agents and merchant-side agents.
The merchant tag and protocol note below describe the live v0.2 registration, dispatch, proposal, and match-token contract: Intent-Matching Protocol v0.2. Merchant registry, heartbeats, health checks, proposal submission, match sessions, and match tokens are live in this gateway.
Merchant-side quick start (v0.2)
- Send `POST /v1/merchant/register` with `merchant_id`, `agent_endpoint`, and optional tags / capabilities. Store the returned `registration_token`.
- Use `X-Merchant-Token` for `POST /v1/merchant/heartbeat`, merchant updates, deactivation, and `POST /v1/proposals`.
- Consume `Intent.Surge` or poll `/v1/intents`, submit `/v1/proposals`, then let demand agents call `/v1/match` or `/v1/recommend` to rank and accept offers.
Experience Commerce Protocol
Experience Commerce adds scene-aware context, preview assets, remix actions, and decision feedback on top of intent/proposal/match.
The live endpoints are `/v1/decision-events` and `/v1/experience-feed`; the OpenAPI schemas also preserve `experience_context`, `experience_preview`, and `experience_card` snapshots. Experience Commerce Protocol.
Experience quick start
- Attach `experience_context` when creating an intent if the buyer needs to visualize or validate fit before purchase.
- Attach `experience_preview` when submitting a proposal; SellToAI synthesizes an `experience_card` for downstream agents.
- Record pick/nope/remix/confirm events through `/v1/decision-events`, or ask `/v1/experience-feed` for ready-to-experience proposal shells.
Commerce Runtime Layer
The runtime endpoint runs one auditable SellToAI Commerce Agent Loop and returns the linked Intent, Proposal, Match Session, Match Token, agent steps, budget, memory refs, skill refs, and runtime trace.
Use `POST /v1/commerce-runtime` from agent hosts that need a single transaction-shaped call instead of manually stitching each object; the design note is here: Commerce Runtime Layer.
Runtime quick start
- Pass `runtime_session`, `commerce_budget`, `commerce_memory_refs`, `skill_refs`, and a normal `intent` payload to start an agent loop.
- Optionally pass a `proposal` shell with merchant/product context; SellToAI fills runtime metadata and creates the linked match token.
- Use the same capability through A2A `run_commerce_runtime`, MCP `run_commerce_runtime`, or the REST endpoint when you need audit and settlement traceability.
A2A Agent Card
Machine-readable A2A card (live) at /.well-known/agent-card.json. Point your agent runtime here so capabilities stay in sync.
Loading…
SKILL.md
Human-readable skill document served at /skills/moras-shop/SKILL.md — byte-for-byte what the installer copies into your agent's skills folder.
Loading…