{"openapi":"3.0.3","info":{"title":"CHECK N BUY STORE API","description":"A global ecommerce marketplace API for browsing products, categories, and accessing shopping information. Public, unauthenticated read endpoints. Current version: v1.","version":"1.0.0","contact":{"name":"CHECK N BUY STORE Support","email":"support@checknbuystore.com","url":"https://checknbuystore.com/contact-us"},"termsOfService":"https://checknbuystore.com/terms-and-conditions","x-api-version":"1","x-deprecation-policy":"Breaking changes ship under a new major version (e.g. /v2). Deprecated versions are announced with a Deprecation header and a minimum 90-day sunset window."},"servers":[{"url":"https://checknbuystore.com","description":"Production"},{"url":"https://checknbuystore.com/api","description":"API base (relative)"}],"tags":["Products","Categories","Content","Agent"],"components":{"schemas":{"Error":{"type":"object","description":"RFC 9457 (application/problem+json) aligned error envelope. Every non-2xx response returns this shape.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code (e.g. RESOURCE_NOT_FOUND, INVALID_REQUEST, RATE_LIMITED, INTERNAL_ERROR).","enum":["RESOURCE_NOT_FOUND","INVALID_REQUEST","RATE_LIMITED","INTERNAL_ERROR"],"example":"RESOURCE_NOT_FOUND"},"message":{"type":"string","example":"Product not found."},"resolution":{"type":"string","description":"Human-readable hint agents can use to recover.","example":"Verify the product slug at /api/products/list"}},"required":["code","message","resolution"]},"type":{"type":"string","format":"uri-reference","example":"/developers#error-resource_not_found"},"title":{"type":"string","example":"Product not found."},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"Product not found."},"requestId":{"type":"string","format":"uuid"},"links":{"type":"object","properties":{"docs":{"type":"string","format":"uri","example":"/developers"},"status":{"type":"string","format":"uri","example":"/developers#status-codes"}}}},"required":["error","status"]},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"sku":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"compare_price":{"type":"number","nullable":true},"stock":{"type":"integer"},"brand":{"type":"string","nullable":true},"image":{"type":"string","nullable":true},"category":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"url":{"type":"string","format":"uri"}}},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"image":{"type":"string","nullable":true},"productCount":{"type":"integer"},"url":{"type":"string","format":"uri"}}}},"parameters":{"AcceptHeader":{"name":"Accept","in":"header","description":"Set 'text/markdown' to receive page content as markdown (only for /api/markdown).","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests. Retry after the Retry-After delay.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/products/{slug}":{"get":{"operationId":"getProduct","summary":"Get a product by slug","description":"Returns detailed information about a single product including price, description, availability, and seller info.","tags":["Products"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The product slug"}],"responses":{"200":{"description":"Product found","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/Product"},"links":{"type":"object"}}}}},"headers":{"X-API-Version":{"schema":{"type":"string"}},"RateLimit":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/products/list":{"get":{"operationId":"listProducts","summary":"List products","description":"Returns a paginated list of products with optional category and search filtering.","tags":["Products"],"parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50,"minimum":1}}],"responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"type":"object"},"links":{"type":"object"}}}}},"headers":{"X-API-Version":{"schema":{"type":"string"}},"RateLimit":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/categories":{"get":{"operationId":"listCategories","summary":"List categories","description":"Returns all active categories with product counts.","tags":["Categories"],"responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"total":{"type":"integer"},"links":{"type":"object"}}}}},"headers":{"X-API-Version":{"schema":{"type":"string"}},"RateLimit":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/markdown":{"get":{"operationId":"getPageMarkdown","summary":"Get page content as markdown","description":"Returns the content of any page in markdown format. Supports static pages and dynamic product/category pages. Content negotiation via Accept: text/markdown.","tags":["Content"],"parameters":[{"name":"original","in":"query","required":true,"schema":{"type":"string"},"description":"The page path to get content for"},{"$ref":"#/components/parameters/AcceptHeader"}],"responses":{"200":{"description":"Page content in markdown","content":{"text/markdown":{"schema":{"type":"string"}}},"headers":{"Vary":{"schema":{"type":"string"}}}},"404":{"description":"Page not found (returns text/markdown with links)","content":{"text/markdown":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/agent":{"get":{"operationId":"getAgentManifest","summary":"Machine-readable agent manifest","description":"Returns name, endpoints, whenToUse, and policies for agents.","tags":["Agent"],"responses":{"200":{"description":"Agent manifest","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-API-Version":{"schema":{"type":"string"}},"RateLimit":{"schema":{"type":"string"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/developers":{"get":{"operationId":"getDeveloperPortal","summary":"Developer portal and API documentation","description":"Human and agent-readable documentation for the public API.","tags":["Agent"],"responses":{"200":{"description":"Developer portal HTML"}}}}}}