{"openapi":"3.0.3","info":{"title":"Integration API","version":"v1","description":"Catalog, order, and content API for an external system. A key only receives the abilities chosen in the admin: catalog:read, catalog:write, orders:read, orders:write-status, content:read, content:write. Prices are integer minor units: 49000 means 490.00. The same abilities will gate MCP tools."},"servers":[{"url":"https:\/\/ouroborosbooks.com.ua\/api\/v1\/integrations"}],"security":[{"bearer":[]}],"tags":[{"name":"Catalog"}],"paths":{"\/products":{"get":{"tags":["Catalog"],"summary":"List products","description":"Requires catalog:read. Paginated catalog. limit defaults to 15 and cannot exceed 50.","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number, starting at 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size. Default 15, maximum 50."},{"name":"filter[name]","in":"query","required":false,"schema":{"type":"string"},"description":"Part of the product name."},{"name":"filter[sku]","in":"query","required":false,"schema":{"type":"string"},"description":"Exact SKU."},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Pass offers to add variants."}],"responses":{"200":{"description":"Product page","content":{"application\/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Product"}},"per_page":{"type":"integer","example":15},"total":{"type":"integer","example":1},"from":{"type":"integer","nullable":true,"example":1},"to":{"type":"integer","nullable":true,"example":1},"last_page":{"type":"integer","example":1},"path":{"type":"string"},"next_page_url":{"type":"string","nullable":true},"prev_page_url":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/products\/{id}":{"get":{"tags":["Catalog"],"summary":"Show one product","description":"Requires catalog:read. Returns the product in data. include=offers adds variants. An unknown id returns 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Product id in this store."},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Pass offers to add variants."}],"responses":{"200":{"description":"One product","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Product"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/catalog\/products\/{external_id}":{"put":{"tags":["Catalog"],"summary":"Create or replace a product","description":"Requires catalog:write. Idempotent upsert by the caller external id. Body fields: name, sku, price, quantity, description, status, image_url, category_external_ids, tag_external_ids. image_url must be a public https image. Category and tag lists must already exist for this key and replace the product links.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Mapped product","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"tags":["Catalog"],"summary":"Update part of a product","description":"Requires catalog:write. Changes only the supplied fields, including category_external_ids and tag_external_ids when present. The product must already exist for this key.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Mapped product","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/catalog\/categories\/{external_id}":{"put":{"tags":["Catalog"],"summary":"Create or rename a category","description":"Requires catalog:write. Body field: name.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Mapped category","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/catalog\/tags\/{external_id}":{"put":{"tags":["Catalog"],"summary":"Create or rename a tag","description":"Requires catalog:write. Body field: value. Status labels are rejected.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Mapped tag","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/orders":{"get":{"tags":["Catalog"],"summary":"List placed orders","description":"Requires orders:read. Cursor pagination with updated_since and cursor. Totals are minor units.","parameters":[{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"},"description":"Only orders updated at or after this timestamp."},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer"},"description":"Return orders with a greater id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size. Default 15, maximum 50."}],"responses":{"200":{"description":"Order page","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/orders\/{reference}\/status":{"post":{"tags":["Catalog"],"summary":"Change an order status","description":"Requires orders:write-status and the Idempotency-Key header. Body field: status. Payment confirmation cannot be set here, and the paid total is not changed. A repeated key returns the first response. Keys with orders:read and a webhook URL receive a signed order.status_changed event.","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"},"description":"Stable order reference."}],"responses":{"200":{"description":"Updated order","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/content\/pages":{"get":{"tags":["Catalog"],"summary":"List pages and posts","description":"Requires content:read. Cursor pagination. Optional type is page or blog.","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"page or blog."},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer"},"description":"Return records with a greater id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size. Default 15, maximum 50."}],"responses":{"200":{"description":"Content list","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/content\/pages\/{external_id}":{"put":{"tags":["Catalog"],"summary":"Create or update a draft page","description":"Requires content:write. Body fields: type (page or blog), title, slug, body. HTML is sanitized. Saving does not publish.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Draft page","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/content\/pages\/{external_id}\/publish":{"post":{"tags":["Catalog"],"summary":"Publish a page","description":"Requires content:write and the Idempotency-Key header.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Published page","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/content\/pages\/{external_id}\/unpublish":{"post":{"tags":["Catalog"],"summary":"Unpublish a page","description":"Requires content:write.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Caller identifier, stable across retries."}],"responses":{"200":{"description":"Unpublished page","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Integration key with the catalog:read ability."}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"integer","description":"Product id in this store."},"name":{"type":"string"},"description":{"type":"string","description":"Plain text."},"sku":{"type":"string","nullable":true,"description":"SKU of the first variant."},"thumbnail_url":{"type":"string","nullable":true},"quantity":{"type":"integer","description":"Sum of variant stock."},"currency_code":{"type":"string","nullable":true},"min_price":{"type":"integer","description":"Lowest variant price in minor units."},"max_price":{"type":"integer","description":"Highest variant price in minor units."},"weight":{"type":"number","nullable":true},"length":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"has_offers":{"type":"boolean","description":"True when the product has more than one variant."},"is_archived":{"type":"boolean","description":"True when the product is not published."},"category_id":{"type":"integer","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"offers":{"type":"array","description":"Present only when include=offers.","items":{"$ref":"#\/components\/schemas\/Offer"}}}},"Offer":{"type":"object","properties":{"id":{"type":"integer"},"sku":{"type":"string","nullable":true},"price":{"type":"integer","description":"Minor units."},"quantity":{"type":"integer"},"properties":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, unknown, or revoked key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Forbidden":{"description":"The key has no catalog:read ability.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"NotFound":{"description":"The product id does not exist.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}