{"openapi":"3.1.0","info":{"title":"Ziffi Commerce API","description":"One API for cross-brand product discovery, pricing, and commerce over every Shopify brand in the Ziffi graph. A free tier lets you try it with no signup (one shared rate limit per IP). Sign up for an `X-Ziffi-Key` to use your key's own higher limit and to attribute usage to your app. Every response is enveloped `{data, provenance, as_of, tier}`; the graph tier is cacheable (ETag), the live tier (price/coupons) is fetched per request.","version":"1.0","contact":{"name":"Ziffi Developers","url":"https://dev.ziffi.xyz"}},"paths":{"/v1/search":{"get":{"tags":["v1"],"summary":"Search","description":"Top results for a query. Capped, no pagination, no total count returned (anti-enumeration): a\nquery gives you the best matches, not a way to walk the catalogue.","operationId":"search_v1_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"free-text query","default":"","title":"Q"},"description":"free-text query"},{"name":"price_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Min"}},{"name":"price_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Max"}},{"name":"in_stock","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock"}},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"}},{"name":"on_sale","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"On Sale"}},{"name":"facets","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON object, e.g. {\"color\":\"navy\"}","title":"Facets"},"description":"JSON object, e.g. {\"color\":\"navy\"}"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"relevance","title":"Sort"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"hybrid | lexical | semantic — which arms run","default":"hybrid","title":"Mode"},"description":"hybrid | lexical | semantic — which arms run"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"description":"top results for this query (no pagination)","default":20,"title":"Limit"},"description":"top results for this query (no pagination)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/products/{ident}":{"get":{"tags":["v1"],"summary":"Product","operationId":"product_v1_products__ident__get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"comma list of includes","title":"Include"},"description":"comma list of includes"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/products/{ident}/price":{"get":{"tags":["v1"],"summary":"Product Price","description":"LIVE tier — client-preferred (storefront fetches from the user's browser); this server path is\nthe bounded fallback + the answer for browserless API/MCP consumers.","operationId":"product_price_v1_products__ident__price_get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/prices":{"post":{"tags":["v1"],"summary":"Prices","description":"Batch live price for a basket. Bounded fan-out (≤20); each entry carries its own `verified`.","operationId":"prices_v1_prices_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_prices_v1_prices_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/coupons":{"get":{"tags":["v1"],"summary":"Coupons","description":"LIVE — discover discount codes that actually work on a brand's Shopify store by testing candidate\ncodes at the live cart (Honey/Coupert-style). Pass ONE of `product`, `brand`, or `domain`. Applicable\ncodes are ranked best-first with the discount each takes off a single-item cart (integer minor units).","operationId":"coupons_v1_coupons_get","parameters":[{"name":"product","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"product_uid (sha:…) or product id (uuid)","title":"Product"},"description":"product_uid (sha:…) or product id (uuid)"},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"brand slug (or its domain)","title":"Brand"},"description":"brand slug (or its domain)"},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"raw Shopify host, e.g. mcaffeine.com","title":"Domain"},"description":"raw Shopify host, e.g. mcaffeine.com"},{"name":"max_candidates","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":40,"title":"Max Candidates"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/suggest":{"get":{"tags":["v1"],"summary":"Suggest","operationId":"suggest_v1_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/recommend":{"get":{"tags":["v1"],"summary":"Recommend","operationId":"recommend_v1_recommend_get","parameters":[{"name":"product_id","in":"query","required":true,"schema":{"type":"string","title":"Product Id"}},{"name":"intent","in":"query","required":false,"schema":{"type":"string","default":"related","title":"Intent"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":12,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/products/{ident}/reviews":{"get":{"tags":["v1"],"summary":"Product Reviews","operationId":"product_reviews_v1_products__ident__reviews_get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/plans":{"get":{"tags":["v1"],"summary":"Plans","description":"The access policy — a free tier for anonymous callers, higher limits with a key (discovery).","operationId":"plans_v1_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/quota":{"get":{"tags":["v1"],"summary":"Quota","description":"Your current rate limit: the free tier if anonymous, or this key's own limit if a key is sent.","operationId":"quota_v1_quota_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/me":{"get":{"tags":["v1"],"summary":"Me","description":"Who this key is + its usage today. The developer dashboard reads this.","operationId":"me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/mcp":{"post":{"tags":["mcp"],"summary":"Mcp","operationId":"mcp_v1_mcp_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_prices_v1_prices_post":{"properties":{"idents":{"items":{"type":"string"},"type":"array","title":"Idents","description":"≤20 product ids/uids"}},"type":"object","required":["idents"],"title":"Body_prices_v1_prices_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ZiffiKey":{"type":"apiKey","in":"header","name":"X-Ziffi-Key","description":"Optional on the free tier. Sending your key applies your key's own (higher) rate limit instead of the shared free-tier limit, and attributes usage to your app."}}},"tags":[{"name":"Discover","description":"Search, browse, suggest, recommend across every brand."},{"name":"Understand","description":"Product detail, attributes, reviews."},{"name":"Price","description":"Live price, batch prices, coupons — live tier, never cached."},{"name":"Platform","description":"Access policy, quota, health, OpenAPI."}],"servers":[{"url":"https://dev.ziffi.xyz","description":"Ziffi API"}]}