{"openapi":"3.0.3","info":{"title":"SellToAI 网关","version":"0.1.0","description":"根据自然语言意图推荐高转化的 TikTok Shop 商品，并附带 KOC 视频与带归因的购买链接；购买链接必须原样交给用户。\n\n在线试玩与接入说明：https://selltoai.ai/ — 可直接调试接口，并复制适用于各主流 Agent 客户端的现成片段。","contact":{"name":"SellToAI","url":"https://selltoai.ai"}},"servers":[{"url":"https://selltoai.ai","description":"生产"}],"tags":[{"name":"recommend","description":"推荐与发现接口；生产客户端调用需使用 Developer API key，portal 公开试玩通道除外。"},{"name":"card","description":"获取或查询已生成的 PCD（商品种草卡）。"},{"name":"creator","description":"浏览创作者带货橱窗。"},{"name":"intent","description":"一等 Intent 对象：把自然语言需求变成可继续撮合的标准输入。"},{"name":"proposal","description":"商家侧 Proposal：围绕某个 Intent 返回结构化报价与履约信息。"},{"name":"match","description":"围绕 Intent + Proposal 生成 Match Session 与 Match Token。"},{"name":"merchant","description":"商家 / 供给侧 Agent 入驻与生命周期接口（持久化注册）。"},{"name":"agents","description":"General Commerce Agent registry: merchant, payment, logistics, creator, demand-side, and SellToAI / Moras core agents."},{"name":"report","description":"供给方 ROI 报表（需 X-Supply-Key）。"},{"name":"developer","description":"开发者账号注册、登录、邀请码验证、API Key 管理与请求日志。"},{"name":"commerce-proof","description":"Outcome-backed creator video assets that external agents can use as commerce proof for proposal generation."},{"name":"billing","description":"Billing and settlement previews."},{"name":"reconciliation","description":"Order reconciliation controls."},{"name":"checkout","description":"Payment/checkout authorization against MatchToken credentials."}],"paths":{"/v1/recommend":{"get":{"tags":["recommend"],"summary":"按自然语言意图推荐商品卡","operationId":"recommendProducts","parameters":[{"name":"intent","in":"query","required":true,"schema":{"type":"string"},"description":"用户自然语言意图，例如「给 3 岁侄子买的礼物」。"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":3}},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"国家或地区 ISO 代码（如 US、UK）。"},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"渠道提示（openclaw、cursor、gemini、chatgpt、hermes 等）。"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"503":{"description":"推荐服务暂时不可用。请稍后重试；如果持续出现，请联系 SellToAI 支持。","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/cards/{recId}":{"get":{"tags":["card"],"summary":"按 recId 查询已生成的 PCD","operationId":"getCardByRecId","parameters":[{"name":"recId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PCD"}}}},"404":{"description":"未找到"}},"security":[{"bearerAuth":[]}]}},"/v1/products/{productId}/card":{"get":{"tags":["card"],"summary":"按已知商品 ID 生成新的 PCD","operationId":"buildCardForProduct","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PCD"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/creators/{username}/showcase":{"get":{"tags":["creator"],"summary":"该创作者下表现突出的带货商品","operationId":"getCreatorShowcase","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":6}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowcaseResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/register":{"post":{"tags":["merchant"],"summary":"注册商家 Agent（意图撮合 v0.2）","description":"登记 webhook 与订阅标签、能力声明与区域范围。当前注册已持久化，支持心跳、健康检查、Proposal 提交与 Intent.Surge 分发。规范见本网关 /docs/INTENT_MATCHING_PROTOCOL.md。","operationId":"registerMerchantAgent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantRegisterRequest"},"example":{"merchant_id":"mch_001","agent_endpoint":"https://agent.merchant.com/webhook","subscription_tags":["camping","outdoor"],"capabilities":["stock_check","price_quote"]}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantRegisterResponse"}}}},"400":{"description":"缺少必填字段"}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/{merchantId}":{"get":{"tags":["merchant"],"summary":"按 merchant_id 查询注册中的商家 Agent","operationId":"getMerchantAgent","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLookupResponse"}}}},"404":{"description":"merchant_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/{merchantId}/health":{"get":{"tags":["merchant"],"summary":"探测商家 Agent 健康状态","operationId":"probeMerchantAgentHealth","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"merchant healthy"},"503":{"description":"merchant unhealthy or unreachable"}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/heartbeat":{"post":{"tags":["merchant"],"summary":"商家 Agent 心跳","operationId":"heartbeatMerchantAgent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchant_id"],"properties":{"merchant_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLookupResponse"}}}},"401":{"description":"missing registration token"},"403":{"description":"invalid registration token"}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/{merchantId}/deactivate":{"post":{"tags":["merchant"],"summary":"停用商家 Agent","operationId":"deactivateMerchantAgent","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLookupResponse"}}}},"401":{"description":"missing registration token"},"403":{"description":"invalid registration token"}},"security":[{"bearerAuth":[]}]}},"/v1/intent-mandates/sign":{"post":{"tags":["intent"],"summary":"签发电商意图凭证","description":"当你的集成已开通该能力时，返回用于有额度边界的 checkout 或 payment 授权流程的 Intent Mandate。","operationId":"signIntentMandate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","amount_limit"],"properties":{"product_id":{"type":"string"},"amount_limit":{"type":"number","exclusiveMinimum":0}}}}}},"responses":{"201":{"description":"Signed mandate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_body"},"503":{"description":"当前集成暂未开放 Intent Mandate 签发能力。"}},"security":[{"bearerAuth":[]}]}},"/v1/intents":{"post":{"tags":["intent"],"summary":"创建一等 Intent","operationId":"createIntent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentCreateRequest"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentResponse"}}}},"400":{"description":"missing_fields"}},"security":[{"bearerAuth":[]}]}},"/v1/intents/{intentId}":{"get":{"tags":["intent"],"summary":"按 intent_id 查询 Intent","operationId":"getIntent","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentResponse"}}}},"404":{"description":"intent_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/intents/{intentId}/proposals":{"get":{"tags":["intent"],"summary":"列出某个 Intent 下的 Proposal","operationId":"listIntentProposals","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_expired","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentProposalListResponse"}}}},"404":{"description":"intent_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/proposals":{"post":{"tags":["proposal"],"summary":"提交 Merchant Proposal","operationId":"createProposal","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalCreateRequest"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResponse"}}}},"401":{"description":"missing registration token"},"403":{"description":"invalid registration token"},"404":{"description":"intent_not_found or merchant_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/proposals/{proposalId}":{"get":{"tags":["proposal"],"summary":"按 proposal_id 查询 Proposal","operationId":"getProposal","parameters":[{"name":"proposalId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResponse"}}}},"404":{"description":"proposal_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/match":{"post":{"tags":["match"],"summary":"基于 Intent 与 Proposal 创建 Match Session","operationId":"createMatchSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchCreateRequest"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchSessionResponse"}}}},"400":{"description":"missing_fields"},"404":{"description":"intent_not_found or proposal_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/match/{matchSessionId}":{"get":{"tags":["match"],"summary":"获取渲染后的 Match Session","operationId":"getMatchSession","parameters":[{"name":"matchSessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRenderedResponse"}}}},"404":{"description":"match_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/match/{matchSessionId}/accept":{"post":{"tags":["match"],"summary":"接受 Proposal 并铸造 / 确认 Match Token","operationId":"acceptMatch","parameters":[{"name":"matchSessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proposal_id":{"type":"string"},"match_token_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchTokenResponse"}}}},"404":{"description":"match_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/match-tokens/{matchTokenId}":{"get":{"tags":["match"],"summary":"按 id 查询 Match Token","operationId":"getMatchToken","parameters":[{"name":"matchTokenId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchTokenResponse"}}}},"404":{"description":"match_token_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/report/attribution":{"get":{"tags":["report"],"summary":"ROI 报表（供给方，需 X-Supply-Key）","operationId":"getAttributionReport","security":[{"supplyKey":[]},{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}},{"name":"channel","in":"query","schema":{"type":"string"}},{"name":"product_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未授权"}}}},"/v1/agents/register":{"post":{"tags":["agents"],"summary":"Register a Commerce Agent","description":"Registers any external commerce agent (merchant/payment/logistics/creator/demand) with protocol and capability declarations.","operationId":"registerCommerceAgent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceAgentRegisterRequest"},"example":{"agent_id":"pay_paypal_demo","agent_type":"payment","endpoint":"https://paypal.example/a2a","protocols":["a2a-jsonrpc","webhook"],"auth_methods":["signed_webhook","intent_mandate"],"capability_profile":{"payment":{"create_checkout":true,"authorize_intent_mandate":true}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceAgentRegisterResponse"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceAgentRegisterResponse"}}}},"400":{"description":"missing_fields"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/import-card":{"post":{"tags":["agents"],"summary":"Import an A2A Agent Card","description":"Imports an inline agent_card or fetches agent_card_url, maps skills/endpoints into a Commerce Agent capability profile, and registers it.","operationId":"importCommerceAgentCard","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceAgentImportCardRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceAgentRegisterResponse"}}}},"502":{"description":"agent_card_fetch_failed"}},"security":[{"bearerAuth":[]}]}},"/v1/agents":{"get":{"tags":["agents"],"summary":"List Commerce Agents","operationId":"listCommerceAgents","parameters":[{"name":"agent_type","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"agents":{"type":"array","items":{"$ref":"#/components/schemas/CommerceAgent"}}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/agents/{agentId}":{"get":{"tags":["agents"],"summary":"Fetch a Commerce Agent","operationId":"getCommerceAgent","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/CommerceAgent"}}}}}},"404":{"description":"agent_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/{agentId}/heartbeat":{"post":{"tags":["agents"],"summary":"Heartbeat a Commerce Agent","operationId":"heartbeatCommerceAgent","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"agent":{"$ref":"#/components/schemas/CommerceAgent"}}}}}},"401":{"description":"X-Agent-Token required"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/{agentId}/deactivate":{"post":{"tags":["agents"],"summary":"Deactivate a Commerce Agent","operationId":"deactivateCommerceAgent","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"agent":{"$ref":"#/components/schemas/CommerceAgent"}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/decision-events":{"post":{"tags":["experience-commerce"],"summary":"Record a proposal/experience decision feedback event","operationId":"recordDecisionEvent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionEventCreateRequest"}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionEventResponse"}}}},"400":{"description":"unsupported_decision_event"}},"security":[{"bearerAuth":[]}]}},"/v1/experience-feed":{"post":{"tags":["experience-commerce"],"summary":"Prepare proactive ready-to-experience proposal shells","operationId":"prepareExperienceFeed","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExperienceFeedRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExperienceFeedResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/developers/register":{"post":{"tags":["developer"],"summary":"注册开发者账号","operationId":"registerDeveloper","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["display_name","contact_email","password"],"properties":{"display_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"company":{"type":"string"},"website":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true},"password":{"type":"string","minLength":8},"invite_code":{"type":"string","description":"Optional invite code; it may also be verified after login."}}}}}},"responses":{"201":{"description":"Developer account created; use developer_token for console management endpoints.","content":{"application/json":{"schema":{"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","additionalProperties":true},"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":{"description":"Invalid registration payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Developer account already exists for this email","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"description":"Creates a password-based developer account and returns a console session token. API keys are created separately after invite verification."}},"/v1/developers/me":{"get":{"tags":["developer"],"summary":"获取当前开发者档案","operationId":"getDeveloperProfile","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Developer profile, console session, invite status, and API keys.","content":{"application/json":{"schema":{"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","additionalProperties":true},"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"description":"Requires a developer_token from register or login, not an API key."}},"/v1/developers/keys":{"get":{"tags":["developer"],"summary":"列出当前开发者的 API Keys","operationId":"listDeveloperApiKeys","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"API keys.","content":{"application/json":{"schema":{"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"description":"Requires a developer_token from register or login."},"post":{"tags":["developer"],"summary":"邀请码验证后创建新的 API Key","operationId":"createDeveloperApiKey","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"API Key 已创建，可复制完整值。","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"api_key":{"type":"string","example":"MA2A.w5FqPdPTN8XcN0dF7aYp3rQeR9sLmK2z"},"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Invite verification is required before creating API keys","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"description":"需要 developer_token 和已验证的邀请码。完整 API key 会随响应返回，也可在开发者控制台再次显示完整值并复制。"}},"/v1/developers/keys/{keyId}/revoke":{"post":{"tags":["developer"],"summary":"停用 API Key（旧接口，建议用 DELETE 删除）","operationId":"revokeDeveloperApiKey","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked.","content":{"application/json":{"schema":{"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"description":"Requires a developer_token from register or login.","deprecated":true}},"/v1/developers/logs":{"get":{"tags":["developer"],"summary":"查看最近的已鉴权请求日志","operationId":"listDeveloperRequestLogs","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Request logs.","content":{"application/json":{"schema":{"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"description":"Requires a developer_token from register or login."}},"/v1/developers/login":{"post":{"tags":["developer"],"summary":"登录开发者控制台","operationId":"loginDeveloper","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_email","password"],"properties":{"contact_email":{"type":"string","format":"email"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Developer console session created.","content":{"application/json":{"schema":{"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","additionalProperties":true},"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":{"description":"Invalid login payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Invalid email or password","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/developers/invite/verify":{"post":{"tags":["developer"],"summary":"验证开发者邀请码","operationId":"verifyDeveloperInvite","description":"Requires a developer_token. API key creation is blocked until invite verification succeeds.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invite_code"],"properties":{"invite_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Invite verified.","content":{"application/json":{"schema":{"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","additionalProperties":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}}},"invite_verified":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Invalid invite code","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/developers/keys/{keyId}":{"patch":{"tags":["developer"],"summary":"修改 API Key 名称","operationId":"updateDeveloperApiKeyLabel","description":"Requires a developer_token from register or login. Updates the key label shown in the developer console.","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"}}}}}},"responses":{"200":{"description":"API key label updated.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"key":{"type":"object","properties":{"key_id":{"type":"string"},"developer_id":{"type":"string"},"key_prefix":{"type":"string","example":"MA2A.w5FqPdPTN..."},"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"delete":{"tags":["developer"],"summary":"删除 API Key","operationId":"deleteDeveloperApiKey","description":"需要 developer_token。删除后的 key 会立即停止鉴权，但记录会保留用于审计和请求日志关联。","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API Key 已删除并保留审计记录。","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"key":{"type":"object","properties":{"key_id":{"type":"string"},"developer_id":{"type":"string"},"key_prefix":{"type":"string","example":"MA2A.w5FqPdPTN..."},"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/developers/keys/{keyId}/reveal":{"post":{"tags":["developer"],"summary":"获取完整 API Key 用于复制","operationId":"revealDeveloperApiKey","description":"Requires a developer_token from register or login. Returns the full API key for keys created after encrypted key storage was enabled.","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full API key returned.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"api_key":{"type":"string","example":"MA2A.w5FqPdPTN8XcN0dF7aYp3rQeR9sLmK2z"},"key":{"type":"object","properties":{"key_id":{"type":"string"},"developer_id":{"type":"string"},"key_prefix":{"type":"string","example":"MA2A.w5FqPdPTN..."},"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":{"description":"Missing or invalid developer session token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"410":{"description":"Full key is unavailable for older hash-only keys","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/proof-feed":{"get":{"tags":["commerce-proof"],"summary":"List commerce proof assets, including automated community proof","description":"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":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":24,"default":12}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["commerce","community","community-proof","reddit"]},"description":"Use community/community-proof/reddit to return automated Community Proof assets."},{"name":"intent","in":"query","required":false,"schema":{"type":"string"},"description":"Shopping intent used to build scoped Reddit search import URLs."},{"name":"products","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated product names used for exact product mention import."},{"name":"subreddits","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated subreddit allowlist for bounded import; not recursive crawling."}],"responses":{"200":{"description":"Commerce or community proof feed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommerceProofFeedResponse"},{"$ref":"#/components/schemas/CommunityProofFeedResponse"}]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/commerce-runtime":{"post":{"tags":["commerce-runtime"],"summary":"Run an auditable SellToAI Commerce Agent Runtime loop","operationId":"createCommerceRuntime","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceRuntimeRequest"}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceRuntimeResponse"}}}},"400":{"description":"missing_intent"}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/{merchantId}/agent-readiness":{"get":{"tags":["merchant"],"summary":"Assess whether a merchant is ready for embedded AI shopping workflows","description":"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.","operationId":"assessMerchantAgentReadiness","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantAgentReadinessResponse"}}}},"404":{"description":"merchant_not_found"}},"security":[{"bearerAuth":[]}]}},"/v1/merchant/dispatch-queue":{"get":{"tags":["merchant"],"summary":"List merchant dispatch queue and DLQ deliveries","operationId":"listMerchantDispatchQueue","security":[{"bearerAuth":[]},{"supplyKey":[]}],"parameters":[{"name":"X-Supply-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Supply/admin key for operational reporting and replay endpoints."},{"name":"state","in":"query","schema":{"type":"string","enum":["pending","inflight","delivered","dlq"]}},{"name":"merchant_id","in":"query","schema":{"type":"string"}},{"name":"intent_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Queue summary and deliveries"},"401":{"description":"Invalid or missing supply key"}}}},"/v1/merchant/dispatch-queue/retry":{"post":{"tags":["merchant"],"summary":"Retry one DLQ delivery or replay all DLQ deliveries","operationId":"retryMerchantDispatchQueue","security":[{"bearerAuth":[]},{"supplyKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string"},"state":{"type":"string","default":"dlq"}}}}}},"responses":{"200":{"description":"Retry results"},"401":{"description":"Invalid or missing supply key"}},"parameters":[{"name":"X-Supply-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Supply/admin key for operational reporting and replay endpoints."}]}},"/v1/merchant/{merchantId}/sla":{"get":{"tags":["merchant"],"summary":"Get merchant SLA metrics from feedback events","operationId":"getMerchantSla","security":[{"bearerAuth":[]},{"supplyKey":[]}],"parameters":[{"name":"X-Supply-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Supply/admin key for operational reporting and replay endpoints."},{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant SLA summary"},"401":{"description":"Invalid or missing supply key"}}}},"/v1/merchant/{merchantId}/reputation":{"get":{"tags":["merchant"],"summary":"Recompute and return merchant reputation snapshot","operationId":"getMerchantReputation","security":[{"bearerAuth":[]},{"supplyKey":[]}],"parameters":[{"name":"X-Supply-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Supply/admin key for operational reporting and replay endpoints."},{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant reputation snapshot"},"401":{"description":"Invalid or missing supply key"}}}},"/v1/match-tokens/{matchTokenId}/payment-authorization":{"post":{"tags":["checkout"],"summary":"Authorize checkout/payment against a verified MatchToken","operationId":"authorizeMatchTokenPayment","security":[{"bearerAuth":[]}],"parameters":[{"name":"matchTokenId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_amount":{"type":"number"},"currency":{"type":"string"},"proposal_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Payment is authorized"},"409":{"description":"Token, proposal, amount, or acceptance state is not valid for payment"}}}},"/v1/reconciliation/tiktok-affiliate/run":{"post":{"tags":["reconciliation"],"summary":"Run TikTok Affiliate order reconciliation","operationId":"runTikTokAffiliateReconciliation","security":[{"bearerAuth":[]},{"supplyKey":[]}],"parameters":[{"name":"X-Supply-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Supply/admin key for operational reporting and replay endpoints."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":30}}}}}},"responses":{"200":{"description":"Reconciliation result"},"401":{"description":"Invalid supply key"}}}},"/v1/billing/settlement-preview":{"post":{"tags":["billing"],"summary":"Preview merchant billing/settlement from attributed orders and accepted matches","operationId":"previewBillingSettlement","security":[{"bearerAuth":[]},{"supplyKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchant_id"],"properties":{"merchant_id":{"type":"string"},"attributed_orders":{"type":"array","items":{"type":"object"}},"qualified_leads":{"type":"integer"},"accepted_matches":{"type":"integer"}}}}}},"responses":{"200":{"description":"Billing preview"},"400":{"description":"Missing merchant id"},"401":{"description":"Invalid or missing supply key"}},"parameters":[{"name":"X-Supply-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Supply/admin key for operational reporting and replay endpoints."}]}},"/v1/agentic-checkout":{"post":{"tags":["agentic-checkout"],"summary":"Create an Agentic Checkout transaction plan","description":"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.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Checkout created and waiting for explicit buyer confirmation","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid checkout request"}}}},"/v1/agentic-checkout/{checkoutId}/confirm":{"post":{"tags":["agentic-checkout"],"summary":"Confirm an Agentic Checkout with MatchToken payment authorization","description":"Requires explicit buyer-agent consent, accepts the signed MatchToken, verifies proposal/amount/currency, and returns a merchant handoff receipt plus audit trail.","security":[{"bearerAuth":[]}],"parameters":[{"name":"checkoutId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Checkout confirmed and authorized for payment or merchant handoff","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Consent, token, proposal, amount, or currency mismatch"}}}}},"components":{"securitySchemes":{"supplyKey":{"type":"apiKey","in":"header","name":"X-Supply-Key"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"SellToAI API key or developer_token"}},"schemas":{"MerchantRegisterRequest":{"type":"object","required":["merchant_id","agent_endpoint"],"properties":{"merchant_id":{"type":"string","description":"Stable merchant / tenant id"},"agent_endpoint":{"type":"string","description":"HTTPS webhook URL for your Agent"},"subscription_tags":{"type":"array","items":{"type":"string"},"description":"Intent tags to subscribe to"},"capabilities":{"type":"array","items":{"type":"string"},"description":"e.g. stock_check, price_quote"},"workflow_context":{"$ref":"#/components/schemas/MerchantWorkflowContext"},"trust_evidence_policy":{"$ref":"#/components/schemas/MerchantTrustEvidencePolicy"},"agent_ready_profile":{"$ref":"#/components/schemas/MerchantAgentReadyProfile"}}},"MerchantRegisterResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"created":{"type":"boolean"},"merchant_id":{"type":"string"},"registration_token":{"type":"string","description":"Secret token used for heartbeat, updates, deactivation, and proposal submission."},"merchant":{"$ref":"#/components/schemas/MerchantAgent"}}},"MerchantLookupResponse":{"type":"object","properties":{"status":{"type":"string","nullable":true},"merchant":{"$ref":"#/components/schemas/MerchantAgent"}}},"MerchantAgent":{"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":{"$ref":"#/components/schemas/MerchantWorkflowContext"},"trust_evidence_policy":{"$ref":"#/components/schemas/MerchantTrustEvidencePolicy"},"agent_ready_profile":{"$ref":"#/components/schemas/MerchantAgentReadyProfile"}}},"IntentCreateRequest":{"type":"object","required":["raw_query"],"properties":{"raw_query":{"type":"string"},"region":{"type":"string","nullable":true},"audience":{"type":"string","nullable":true},"budget_range":{"type":"object","properties":{"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true}}},"constraints":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object"},{"type":"string"}]},"time_window":{"type":"object","nullable":true,"description":"Purchase deadline/urgency window used by agentic commerce workflows."},"asset_refs":{"type":"array","items":{"type":"object"},"description":"Evidence/content/product references supplied or produced by Agents/MCP tools."},"attribution_chain":{"type":"array","items":{"type":"object"},"description":"Ordered agents/tools/skills that contributed to intent or proposal creation."},"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."}}},"IntentObject":{"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","nullable":true,"description":"Purchase deadline/urgency window used by agentic commerce workflows."},"asset_refs":{"type":"array","items":{"type":"object"},"description":"Evidence/content/product references supplied or produced by Agents/MCP tools."},"attribution_chain":{"type":"array","items":{"type":"object"},"description":"Ordered agents/tools/skills that contributed to intent or proposal creation."},"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."}}},"IntentResponse":{"type":"object","properties":{"intent":{"$ref":"#/components/schemas/IntentObject"}}},"ProposalCreateRequest":{"type":"object","required":["merchant_agent_id","intent_id","product_id"],"properties":{"merchant_agent_id":{"type":"string"},"intent_id":{"type":"string"},"product_id":{"type":"string"},"offer_title":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"inventory_status":{"type":"string","nullable":true},"shipping_commitment":{"type":"object","nullable":true},"commission_plan":{"type":"object","nullable":true},"service_terms":{"type":"object","nullable":true},"evidence":{"type":"array","items":{"type":"object"}},"valid_until":{"type":"string","format":"date-time","nullable":true},"product_snapshot":{"type":"object","nullable":true},"metadata":{"type":"object","nullable":true},"asset_refs":{"type":"array","items":{"type":"object"},"description":"Evidence/content/product references supplied or produced by Agents/MCP tools."},"trust_score":{"type":"object","description":"Normalized trust/risk score and basis used for ranking/audit."},"attribution_chain":{"type":"array","items":{"type":"object"},"description":"Ordered agents/tools/skills that contributed to intent or proposal creation."},"proposal_state":{"type":"string","enum":["draft","quoted","pending_confirmation","accepted","settled","expired"],"description":"Commerce proposal lifecycle state."},"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."}}},"ProposalObject":{"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"},"description":"Evidence/content/product references supplied or produced by Agents/MCP tools."},"trust_score":{"type":"object","description":"Normalized trust/risk score and basis used for ranking/audit."},"attribution_chain":{"type":"array","items":{"type":"object"},"description":"Ordered agents/tools/skills that contributed to intent or proposal creation."},"proposal_state":{"type":"string","enum":["draft","quoted","pending_confirmation","accepted","settled","expired"],"description":"Commerce proposal lifecycle state."},"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","nullable":true}}},"ProposalResponse":{"type":"object","properties":{"proposal":{"$ref":"#/components/schemas/ProposalObject"}}},"IntentProposalListResponse":{"type":"object","properties":{"intent_id":{"type":"string"},"count":{"type":"integer"},"proposals":{"type":"array","items":{"$ref":"#/components/schemas/ProposalObject"}}}},"MatchCreateRequest":{"type":"object","required":["intent_id"],"properties":{"intent_id":{"type":"string"},"proposal_ids":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":10,"default":3}}},"MatchSessionObject":{"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}}},"MatchTokenObject":{"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}}},"MatchSessionResponse":{"type":"object","properties":{"match_session":{"$ref":"#/components/schemas/MatchSessionObject"}}},"MatchRenderedResponse":{"type":"object","properties":{"match_session":{"$ref":"#/components/schemas/MatchSessionObject"},"ranked_proposals":{"type":"array","items":{"type":"object"}},"match_tokens":{"type":"array","items":{"$ref":"#/components/schemas/MatchTokenObject"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/PCD"}}}},"MatchTokenResponse":{"type":"object","properties":{"match_token":{"$ref":"#/components/schemas/MatchTokenObject"}}},"RecommendResponse":{"type":"object","properties":{"intent":{"type":"string"},"intent_id":{"type":"string"},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PCD"}},"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","nullable":true,"description":"Optional machine hint e.g. intent_plus_trending, trending_suggested."},"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"}}},"ShowcaseResponse":{"type":"object","properties":{"username":{"type":"string"},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PCD"}}}},"PCD":{"type":"object","description":"商品种草卡（PCD）— 推荐与归因的最小单元。","required":["rec_id","product","hero_pitch","selection_story","videos","cta","generated_at"],"properties":{"rec_id":{"type":"string","description":"全局唯一推荐 ID；归因主键。"},"product":{"$ref":"#/components/schemas/Product"},"hero_pitch":{"$ref":"#/components/schemas/HeroPitch"},"selection_story":{"$ref":"#/components/schemas/SelectionStory"},"videos":{"type":"array","items":{"$ref":"#/components/schemas/KocVideo"}},"cta":{"$ref":"#/components/schemas/Cta"},"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}}},"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}}},"HeroPitch":{"type":"object","properties":{"one_liner":{"type":"string"},"why_it_wins_on_tiktok":{"type":"string"},"key_benefits":{"type":"array","items":{"type":"object","properties":{"icon":{"type":"string"},"title":{"type":"string"},"desc":{"type":"string"}}}},"target_audience":{"type":"object","properties":{"persona":{"type":"string"},"age":{"type":"string"},"region":{"type":"array","items":{"type":"string"}}}}}},"SelectionStory":{"type":"object","properties":{"headline":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"moras_score":{"type":"number"}}},"KocVideo":{"type":"object","properties":{"task_id":{"type":"string"},"creator":{"type":"object","properties":{"username":{"type":"string"},"display_name":{"type":"string"},"avatar":{"type":"string","nullable":true},"followers":{"type":"integer"}}},"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":"必须原样交给用户 — 内含归因 rec_id。"}}},"secondary":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}}}},"CommerceAgentRegisterRequest":{"type":"object","required":["agent_id","endpoint"],"properties":{"agent_id":{"type":"string"},"agent_type":{"type":"string","enum":["merchant","payment","logistics","creator","demand","moras-core","other"]},"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"}}},"CommerceAgentImportCardRequest":{"type":"object","properties":{"agent_card":{"type":"object"},"agent_card_url":{"type":"string"},"agent_id":{"type":"string"},"agent_type":{"type":"string"},"metadata":{"type":"object"}}},"CommerceAgentRegisterResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"created":{"type":"boolean"},"agent_id":{"type":"string"},"registration_token":{"type":"string","description":"Secret token for heartbeat, updates and deactivation."},"agent":{"$ref":"#/components/schemas/CommerceAgent"}}},"CommerceAgent":{"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}}},"ExperienceCard":{"type":"object","properties":{"experience_id":{"type":"string"},"intent_id":{"type":"string","nullable":true},"proposal_id":{"type":"string","nullable":true},"scene":{"type":"object"},"preview":{"type":"object"},"products":{"type":"array","items":{"type":"object"}},"creator_evidence":{"type":"array","items":{"type":"object"}},"why_it_fits_you":{"type":"array","items":{"type":"string"}},"remix_actions":{"type":"array","items":{"type":"string"}},"cta":{"type":"object"}}},"DecisionEventCreateRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["proposal.picked","proposal.noped","proposal.remixed","proposal.confirmed","experience.generated","experience.viewed"]},"intent_id":{"type":"string"},"proposal_id":{"type":"string"},"match_token_id":{"type":"string"},"rec_id":{"type":"string"},"action":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"reason":{"type":"string"},"actor_agent_id":{"type":"string"},"experience_id":{"type":"string"},"metadata":{"type":"object"}}},"DecisionEventObject":{"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}}},"DecisionEventResponse":{"type":"object","properties":{"decision_event":{"$ref":"#/components/schemas/DecisionEventObject"}}},"ExperienceFeedRequest":{"type":"object","properties":{"agent_id":{"type":"string"},"taste_profile":{"type":"object"},"inspiration_refs":{"type":"array","items":{"type":"object"}},"limit":{"type":"integer","minimum":1,"maximum":10}}},"ExperienceFeedObject":{"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"}}},"ExperienceFeedResponse":{"type":"object","properties":{"feed":{"$ref":"#/components/schemas/ExperienceFeedObject"}}},"CommerceBudget":{"type":"object","description":"Runtime guardrails for Agentic Commerce execution.","properties":{"max_agent_iterations":{"type":"integer","minimum":1},"max_merchant_queries":{"type":"integer","minimum":1},"max_proposal_versions":{"type":"integer","minimum":1},"require_user_confirmation_before_payment":{"type":"boolean","default":true}}},"RuntimeSession":{"type":"object","description":"One Commerce Agent Loop runtime context.","properties":{"runtime_id":{"type":"string"},"entry_agent_id":{"type":"string"},"mode":{"type":"string"},"stage":{"type":"string"},"started_at":{"type":"string","format":"date-time"}}},"AgentStep":{"type":"object","description":"Auditable step in the Commerce Agent Loop.","properties":{"step_id":{"type":"string"},"agent_id":{"type":"string"},"role":{"type":"string"},"action":{"type":"string"},"status":{"type":"string"},"input_refs":{"type":"array","items":{"type":"string"}},"output_refs":{"type":"array","items":{"type":"string"}}}},"CommerceMemoryRef":{"type":"object","properties":{"type":{"type":"string","enum":["user_taste_memory","merchant_trust_memory","asset_memory","deal_memory","other"]},"ref_id":{"type":"string"},"summary":{"type":"string"}}},"RuntimeTrace":{"type":"object","properties":{"loop":{"type":"array","items":{"type":"string"}},"current_step":{"type":"string"},"audit_status":{"type":"string"}}},"CommerceRuntimeRequest":{"type":"object","required":["intent"],"properties":{"intent":{"type":"object","description":"Intent payload; accepts raw_query/intent, budget, constraints and protocol fields."},"runtime_session":{"$ref":"#/components/schemas/RuntimeSession"},"agent_steps":{"type":"array","items":{"$ref":"#/components/schemas/AgentStep"}},"commerce_budget":{"$ref":"#/components/schemas/CommerceBudget"},"commerce_memory_refs":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMemoryRef"}},"skill_refs":{"type":"array","items":{"type":"string"}},"runtime_trace":{"$ref":"#/components/schemas/RuntimeTrace"},"proposal":{"type":"object","description":"Optional proposal seed for the Deal Agent step."}}},"CommerceRuntimeObject":{"type":"object","properties":{"runtime_session":{"$ref":"#/components/schemas/RuntimeSession"},"intent":{"$ref":"#/components/schemas/IntentObject"},"proposal":{"$ref":"#/components/schemas/ProposalObject"},"match_session":{"$ref":"#/components/schemas/MatchSessionObject"},"match_token":{"$ref":"#/components/schemas/MatchTokenObject"},"agent_steps":{"type":"array","items":{"$ref":"#/components/schemas/AgentStep"}},"commerce_budget":{"$ref":"#/components/schemas/CommerceBudget"},"commerce_memory_refs":{"type":"array","items":{"$ref":"#/components/schemas/CommerceMemoryRef"}},"skill_refs":{"type":"array","items":{"type":"string"}},"runtime_trace":{"$ref":"#/components/schemas/RuntimeTrace"}}},"CommerceRuntimeResponse":{"type":"object","properties":{"runtime":{"$ref":"#/components/schemas/CommerceRuntimeObject"}}},"CommerceProofFeedResponse":{"type":"object","required":["kind","source","summary","items"],"properties":{"kind":{"type":"string","enum":["commerce_proof_feed"]},"source":{"type":"string","description":"moras_bi source name or fallback when BI is unavailable"},"summary":{"type":"object","properties":{"positioning_i18n":{"type":"object","properties":{"en":{"type":"string"},"zh":{"type":"string"}}},"audience_paths":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"promise":{"type":"string"}}}}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/CommerceProofAsset"}}}},"CommerceProofAsset":{"type":"object","required":["asset_id","title","video","product","creator","performance","commerce_graph","a2a","ctas"],"properties":{"asset_id":{"type":"string"},"title":{"type":"string"},"video":{"type":"object","properties":{"task_id":{"type":"string"},"asset_url":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tiktok_url":{"type":"string","nullable":true},"video_oss_path":{"type":"string","nullable":true},"thumbnail_oss_path":{"type":"string","nullable":true},"tiktok_video_id":{"type":"string","nullable":true}}},"product":{"type":"object","properties":{"product_id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"buy_url":{"type":"string","description":"TikTok Shop product or affiliate URL for the proof asset. Pass through verbatim."}}},"creator":{"type":"object","properties":{"handle":{"type":"string"},"display_name":{"type":"string"}}},"performance":{"type":"object","properties":{"gmv_bucket":{"type":"string","description":"Public, de-identified GMV range. Exact GMV is intentionally not exposed."},"gmv_public_label":{"type":"string","description":"Display label for the public GMV range."},"orders":{"type":"integer"},"views":{"type":"integer"},"likes":{"type":"integer"}}},"commerce_graph":{"type":"object","properties":{"intent_tags":{"type":"array","items":{"type":"string"}},"evidence_type":{"type":"string"},"conversion_score":{"type":"integer"},"trust_signal":{"type":"string"}}},"a2a":{"type":"object","properties":{"asset_ref":{"type":"string"},"proposal_action":{"type":"string"},"attribution_hint":{"type":"string"}}},"ctas":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"label":{"type":"string"},"href":{"type":"string"}}}}}},"CommunityProofFeedResponse":{"type":"object","required":["kind","source","import_mode","no_full_crawl","summary","automation_plan","items"],"properties":{"kind":{"type":"string","enum":["community_proof_feed"]},"source":{"type":"string"},"import_mode":{"type":"string","enum":["query_scoped_auto_import"]},"no_full_crawl":{"type":"boolean","example":true},"summary":{"type":"object","properties":{"positioning":{"type":"string"},"roi_model":{"type":"string"}}},"automation_plan":{"type":"object","properties":{"mode":{"type":"string"},"no_full_crawl":{"type":"boolean"},"trigger":{"type":"string"},"dedupe_key":{"type":"string"},"refresh_policy":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"scope":{"type":"string"},"url":{"type":"string"},"reason":{"type":"string"}}}}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/CommunityProofAsset"}}}},"CommunityProofAsset":{"type":"object","required":["asset_id","source_platform","thread_title","consensus_score","controversy_score","ingestion","a2a"],"properties":{"asset_id":{"type":"string"},"source_platform":{"type":"string","example":"reddit"},"source_url":{"type":"string","nullable":true},"subreddit":{"type":"string","nullable":true},"thread_title":{"type":"string"},"product_mentions":{"type":"array","items":{"type":"string"}},"intent_tags":{"type":"array","items":{"type":"string"}},"positive_points":{"type":"array","items":{"type":"string"}},"negative_points":{"type":"array","items":{"type":"string"}},"alternatives":{"type":"array","items":{"type":"string"}},"consensus_score":{"type":"number","minimum":0,"maximum":1},"controversy_score":{"type":"number","minimum":0,"maximum":1},"freshness_days":{"type":"integer","nullable":true},"trust_signal":{"type":"string"},"engagement":{"type":"object","properties":{"upvotes":{"type":"integer"},"comments":{"type":"integer"}}},"ingestion":{"type":"object","properties":{"mode":{"type":"string"},"source_kind":{"type":"string"},"human_curation_required":{"type":"boolean"}}},"a2a":{"type":"object","properties":{"asset_ref":{"type":"string","example":"moras://community-proof/community_abc123"},"proposal_action":{"type":"string"},"attribution_hint":{"type":"string"}}}}},"MerchantWorkflowContext":{"type":"object","description":"Where AI demand originates and which context fields make the intent actionable.","properties":{"origin_workflow":{"type":"string","example":"ChatGPT shopping research"},"accepted_intent_shapes":{"type":"array","items":{"type":"string"}},"required_context":{"type":"array","items":{"type":"string"},"example":["budget","use_case","constraints"]},"proposal_response_sla_seconds":{"type":"integer","minimum":0},"checkout_modes":{"type":"array","items":{"type":"string"},"example":["agent_redirect","merchant_checkout"]}}},"MerchantTrustEvidencePolicy":{"type":"object","description":"Portable evidence requirements buyer-side agents can inspect before ranking a proposal.","properties":{"community_proof_required":{"type":"boolean"},"accepted_sources":{"type":"array","items":{"type":"string"},"example":["reddit","creator-video","merchant-sla"]},"min_consensus_score":{"type":"number","minimum":0,"maximum":1},"contradiction_handling":{"type":"string"}}},"MerchantAgentReadyProfile":{"type":"object","description":"Supply-side declarations for becoming callable from embedded AI workflows.","properties":{"destination_strategy":{"type":"string","example":"embedded_workflow"},"proposal_contract":{"type":"string","example":"committed_offer_with_evidence"},"attribution_mode":{"type":"string","example":"match_token_required"}}},"MerchantAgentReadinessResponse":{"type":"object","properties":{"kind":{"type":"string","example":"agent_ready_merchant_readiness"},"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","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail"]},"points":{"type":"integer"},"message":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}}}}},"merchant":{"$ref":"#/components/schemas/MerchantAgent"}}}}}}