{"openapi":"3.0.3","info":{"title":"Moras A2A Gateway","version":"0.1.0","description":"Recommend high-converting TikTok Shop products with KOC videos. Each card carries an attribution-tracking buy link that MUST be passed to the user verbatim.\n\nBrowser playground & integration guides: https://a2a.moras.ai/ — try the API live, copy ready-made snippets for OpenClaw / Cursor / Claude Code / ChatGPT / Gemini / Codex / Hermes.","contact":{"name":"Moras","url":"https://moras.ai"}},"servers":[{"url":"https://a2a.moras.ai","description":"production"}],"tags":[{"name":"recommend","description":"Discovery endpoints — public, free, optional channel header."},{"name":"card","description":"Hydrate or look up a previously generated PCD."},{"name":"creator","description":"Browse a creator's showcase."},{"name":"intent","description":"First-class intent objects for true A2A commerce flows."},{"name":"proposal","description":"Merchant proposals attached to an intent."},{"name":"match","description":"Rank proposals into match sessions and mint match tokens."},{"name":"merchant","description":"Merchant / supply-side Agent registry and lifecycle endpoints."},{"name":"report","description":"Supply-side ROI reports (auth required)."}],"paths":{"/v1/recommend":{"get":{"tags":["recommend"],"summary":"Recommend product cards by natural-language intent","operationId":"recommendProducts","parameters":[{"name":"intent","in":"query","required":true,"schema":{"type":"string"},"description":"User's natural-language intent. e.g. \"gift for my 3yo nephew\"."},{"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 country code (US, UK, ...)"},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"Channel hint (openclaw|cursor|gemini|chatgpt|hermes|...)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"503":{"description":"Intent engine unavailable — set GOOGLE_API_KEY or GEMINI_API_KEY on the gateway. Intent is resolved only via Gemini (no offline dictionary).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"intent_engine_unavailable"},"message":{"type":"string"}}}}}}}}},"/v1/cards/{recId}":{"get":{"tags":["card"],"summary":"Look up a previously generated PCD by recId","operationId":"getCardByRecId","parameters":[{"name":"recId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PCD"}}}},"404":{"description":"not found"}}}},"/v1/products/{productId}/card":{"get":{"tags":["card"],"summary":"Build a fresh PCD for a known product id","operationId":"buildCardForProduct","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PCD"}}}}}}},"/v1/creators/{username}/showcase":{"get":{"tags":["creator"],"summary":"Top products this creator has produced winning videos for","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":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowcaseResponse"}}}}}}},"/v1/merchant/register":{"post":{"tags":["merchant"],"summary":"Register a merchant Agent (intent-matching v0.1)","description":"Registers a merchant agent endpoint, subscription tags, capabilities, and routing scope for Moras A2A. 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.","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":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantRegisterResponse"}}}},"400":{"description":"missing_fields — merchant_id and agent_endpoint required"}}}},"/v1/merchant/{merchantId}":{"get":{"tags":["merchant"],"summary":"Fetch a registered merchant 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"}}}},"/v1/merchant/{merchantId}/health":{"get":{"tags":["merchant"],"summary":"Probe merchant Agent health","operationId":"probeMerchantAgentHealth","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"merchant healthy"},"503":{"description":"merchant unhealthy or unreachable"}}}},"/v1/merchant/heartbeat":{"post":{"tags":["merchant"],"summary":"Heartbeat a merchant 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"}}}},"/v1/merchant/{merchantId}/deactivate":{"post":{"tags":["merchant"],"summary":"Deactivate a merchant 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"}}}},"/v1/intent-mandates/sign":{"post":{"tags":["intent"],"summary":"Sign a commerce intent mandate (RSA-SHA256 over canonical payload)","description":"Returns a signed Intent Mandate for checkout flows. Requires MORAS_PRIVATE_KEY (RSA PEM) on the gateway; returns 503 if unset.","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":"MORAS_PRIVATE_KEY not configured"}}}},"/v1/intents":{"post":{"tags":["intent"],"summary":"Create a first-class intent","operationId":"createIntent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentCreateRequest"}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentResponse"}}}},"400":{"description":"missing_fields"}}}},"/v1/intents/{intentId}":{"get":{"tags":["intent"],"summary":"Fetch an intent by id","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"}}}},"/v1/intents/{intentId}/proposals":{"get":{"tags":["intent"],"summary":"List proposals attached to an intent","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"}}}},"/v1/proposals":{"post":{"tags":["proposal"],"summary":"Submit a merchant proposal","operationId":"createProposal","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalCreateRequest"}}}},"responses":{"201":{"description":"created","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"}}}},"/v1/proposals/{proposalId}":{"get":{"tags":["proposal"],"summary":"Fetch a proposal by id","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"}}}},"/v1/match":{"post":{"tags":["match"],"summary":"Create a match session from an intent and proposals","operationId":"createMatchSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchCreateRequest"}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchSessionResponse"}}}},"400":{"description":"missing_fields"},"404":{"description":"intent_not_found or proposal_not_found"}}}},"/v1/match/{matchSessionId}":{"get":{"tags":["match"],"summary":"Fetch a rendered 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"}}}},"/v1/match/{matchSessionId}/accept":{"post":{"tags":["match"],"summary":"Accept a ranked proposal and mint or confirm the 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"}}}},"/v1/match-tokens/{matchTokenId}":{"get":{"tags":["match"],"summary":"Fetch a match token by id","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"}}}},"/v1/report/attribution":{"get":{"tags":["report"],"summary":"ROI report (supply side, requires X-Supply-Key)","operationId":"getAttributionReport","security":[{"supplyKey":[]}],"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":"OK"},"401":{"description":"unauthorized"}}}}},"components":{"securitySchemes":{"supplyKey":{"type":"apiKey","in":"header","name":"X-Supply-Key"}},"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"}}},"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}}},"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"}]}}},"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}}},"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}}},"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}}},"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":"Product Card Document — the atomic recommendation unit.","required":["rec_id","product","hero_pitch","selection_story","videos","cta","generated_at"],"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":"#/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":"MUST be passed to user verbatim — carries attribution rec_id."}}},"secondary":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}}}}}}}