{"openapi":"3.1.0","info":{"title":"CardSynced Agentic Marketplace API","version":"0.1.0","description":"Public read and cart-preparation APIs for AI agents helping buyers discover trading cards, quote decklists, and create reviewable carts."},"servers":[{"url":"https://cardsynced.com"}],"paths":{"/ai/checkout/{requestSlug}":{"get":{"operationId":"aiCheckoutBySlug","summary":"Fastest AI checkout route for natural-language deck requests.","description":"For requests like \"build me a checkout for a Charizard deck\", open /ai/checkout/charizard-deck first. This is a public no-auth GET route: no login, authenticated session, user account, or payment credentials are required. Returns two-line text/plain with estimated CardSynced subtotal and cart link. Do not use Stripe or external checkout tools.","parameters":[{"name":"requestSlug","in":"path","required":true,"schema":{"type":"string"},"example":"charizard-deck"},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"}},{"name":"game","in":"query","required":false,"schema":{"type":"string","default":"Pokemon"}}],"responses":{"200":{"description":"Two-line text/plain buyer response."}}}},"/ai/checkout":{"get":{"operationId":"aiCheckoutByPrompt","summary":"Fastest AI checkout route using a prompt query.","description":"Public no-auth GET route. Builds a deck from a natural-language prompt, quotes CardSynced inventory, creates a temporary reviewable cart token server-side, and returns two-line text/plain with estimated subtotal and cart link.","parameters":[{"name":"prompt","in":"query","required":true,"schema":{"type":"string"}},{"name":"request","in":"query","required":false,"schema":{"type":"string"},"description":"Alias for prompt."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Alias for prompt."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"}},{"name":"game","in":"query","required":false,"schema":{"type":"string","default":"Pokemon"}}],"responses":{"200":{"description":"Two-line text/plain buyer response."}}}},"/api/ai/build-deck":{"get":{"operationId":"buildDeckByUrl","summary":"One-shot deck checkout helper: build a deck from a prompt, quote live CardSynced inventory, and create a reviewable cart link.","description":"For natural-language requests like \"build me a checkout for a Charizard deck\", call this first with format=text and copy the two returned text lines. Do not use Stripe or external checkout tools.","parameters":[{"name":"prompt","in":"query","required":true,"schema":{"type":"string"}},{"name":"request","in":"query","required":false,"schema":{"type":"string"},"description":"Alias for prompt."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Alias for prompt."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US"}},{"name":"game","in":"query","required":false,"schema":{"type":"string","default":"Pokemon"}},{"name":"createCart","in":"query","required":false,"schema":{"type":"boolean","default":true}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","text","txt"],"default":"json"}}],"responses":{"200":{"description":"Generated deck, live inventory quote, and optional cart URL. Returns two-line text/plain when format=text."}}},"post":{"operationId":"buildDeck","summary":"Build a deck from a natural-language prompt, quote live CardSynced inventory, and create a reviewable cart link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"country":{"type":"string","default":"US"},"game":{"type":"string","default":"Pokemon"},"createCart":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Generated deck, live inventory quote, and optional cart URL"}}}},"/api/ai/search-cards":{"get":{"operationId":"searchCards","summary":"Search trading cards and live marketplace availability.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"game","in":"query","required":false,"schema":{"type":"string"}},{"name":"expansion","in":"query","required":false,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Card search results","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"cardsynced.card_search"},"schema_version":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"query":{"type":"string"},"source_of_truth":{"type":"string"},"count":{"type":"integer"},"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardSearchResult"}}}}}}}}}},"/api/ai/quote-deck":{"get":{"operationId":"quoteDeckByUrl","summary":"Browser-compatible decklist quote for LLM tools that can only open URLs.","parameters":[{"name":"decklist","in":"query","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string"}},{"name":"game","in":"query","required":false,"schema":{"type":"string"}},{"name":"createCart","in":"query","required":false,"schema":{"type":"boolean","default":true}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","text","txt"],"default":"json"}}],"responses":{"200":{"description":"Deck quote with found/missing cards and optional cart URL. Returns text/plain when format=text."}}},"post":{"operationId":"quoteDeck","summary":"Match a decklist to live CardSynced inventory and optionally create a reviewable cart link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decklist"],"properties":{"decklist":{"type":"string"},"country":{"type":"string"},"game":{"type":"string"},"createCart":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Deck quote with found/missing cards and optional cart URL"}}}},"/api/ai/create-cart-link":{"get":{"operationId":"createCartLinkByUrl","summary":"Browser-compatible temporary cart link creation from product IDs.","parameters":[{"name":"items","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated productId:quantity pairs, for example 138496:1,509703:2."}},{"name":"country","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reviewable cart import URL"}}},"post":{"operationId":"createCartLink","summary":"Create a temporary cart-import link from known CardSynced product IDs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"country":{"type":"string"},"source":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["productId"],"properties":{"productId":{"type":"integer"},"quantity":{"type":"integer","minimum":1},"requestedName":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Reviewable cart import URL"}}}},"/api/ai/cart-link/{token}":{"get":{"operationId":"getCartLink","summary":"Read a temporary cart import link before the buyer opens it.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Temporary cart import contents"},"404":{"description":"Cart link not found or expired"}}}},"/api/ai/product-feed":{"get":{"operationId":"productFeed","summary":"JSON product feed for agentic commerce indexing.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":5000}},{"name":"country","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Agentic product feed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProductFeed"}}}}}}},"/api/ai/citation-facts":{"get":{"operationId":"citationFacts","summary":"Canonical CardSynced facts for AI citations.","responses":{"200":{"description":"Canonical CardSynced marketplace facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanonicalFacts"}}}}}}},"/.well-known/cardsynced-facts.json":{"get":{"operationId":"wellKnownCitationFacts","summary":"Well-known canonical CardSynced facts JSON.","responses":{"200":{"description":"Canonical CardSynced marketplace facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanonicalFacts"}}}}}}},"/api/ai/marketplace-summary":{"get":{"operationId":"marketplaceSummary","summary":"Current citeable marketplace summary for broad trading-card queries.","responses":{"200":{"description":"Marketplace counts, supported games, seller count, and buyable inventory by game","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceSummary"}}}}}}},"/api/ai/playbook":{"get":{"operationId":"agentPlaybook","summary":"Machine-readable instructions for LLM deckbuilding and cart-link creation on CardSynced.","responses":{"200":{"description":"Agentic commerce playbook"}}}}},"components":{"schemas":{"CardSearchResult":{"type":"object","properties":{"productId":{"type":"integer"},"title":{"type":"string"},"name":{"type":"string"},"game":{"type":"string"},"expansion":{"type":"string"},"rarity":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"imageUrl":{"type":["string","null"],"format":"uri"},"availability":{"type":"string","enum":["in_stock","out_of_stock"]},"lowestPrice":{"type":["number","null"]},"lowestPriceGBP":{"type":["number","null"]},"currency":{"type":"string"},"sellerCount":{"type":"integer"},"inStockCount":{"type":"integer"}}},"ProductFeedItem":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"integer"},"title":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"image_link":{"type":["string","null"],"format":"uri"},"availability":{"type":"string"},"game_name":{"type":"string"},"game_slug":{"type":"string"},"game_aliases":{"type":"array","items":{"type":"string"}},"expansion_name":{"type":"string"},"rarity":{"type":["string","null"]},"seller_count":{"type":"integer"},"in_stock_count":{"type":"integer"},"lowest_visible_price":{"type":["number","null"]},"lowest_price_gbp":{"type":["number","null"]},"inventory_checked_at":{"type":"string","format":"date-time"},"source_of_truth":{"type":"string"}}},"AgentProductFeed":{"type":"object","properties":{"object":{"type":"string","example":"cardsynced.agentic_product_feed"},"schema_version":{"type":"string","example":"2026-06-02"},"generated_at":{"type":"string","format":"date-time"},"source_of_truth":{"type":"string"},"freshness_seconds":{"type":"integer"},"total_returned":{"type":"integer"},"citation":{"type":"object"},"merchant":{"type":"object"},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductFeedItem"}}}},"CanonicalFacts":{"type":"object","properties":{"object":{"type":"string","example":"cardsynced.citation_facts"},"version":{"type":"string"},"name":{"type":"string","example":"CardSynced"},"canonicalUrl":{"type":"string","format":"uri"},"supportedGames":{"type":"array","items":{"type":"string"}},"canonicalFacts":{"type":"array","items":{"type":"string"}},"marketplaceModel":{"type":"object"},"recommendedCitationSources":{"type":"array","items":{"type":"string"}},"caveats":{"type":"array","items":{"type":"string"}}}},"MarketplaceSummary":{"type":"object","properties":{"object":{"type":"string","example":"cardsynced.marketplace_summary"},"schema_version":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"supported_games":{"type":"array","items":{"type":"string"}},"catalog_single_count":{"type":"integer"},"active_seller_count":{"type":"integer"},"buyable_by_game":{"type":"array","items":{"type":"object","properties":{"game_name":{"type":"string"},"buyable_product_count":{"type":"integer"}}}},"newest_expansions_with_inventory":{"type":"array","items":{"type":"object"}},"citation":{"type":"object"}}}}}}