{"openapi":"3.1.0","info":{"title":"Market Category Booster API","summary":"Maps a free-text product description onto the category taxonomy of a marketplace.","description":"Categorizes a product description against the live taxonomy of a marketplace (Amazon, eBay, Shopify, Google), returning the full path: one match per taxonomy level, from the broadest category down to the most specific one.\n\nA request is served if it carries either a valid `X-API-Key` or a valid x402 payment proof in `PAYMENT-SIGNATURE`; with neither it gets `402` and the payment requirements. An API key that is present but invalid gets `401`, not `402`.\n\nThe same behaviour is available to agents over MCP at `https://market-category-booster.com/mcp/`, and described in plain text at `https://market-category-booster.com/llms.txt`.","version":"0.1.3","x-logo":{"url":"/static/assets/img/cat-logo-32.png"}},"servers":[{"url":"https://market-category-booster.com"}],"paths":{"/categorizations":{"get":{"summary":"Get Categorizations","operationId":"get_categorizations_categorizations_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ProductCategorizationOut"},"type":"array","title":"Response Get Categorizations Categorizations Get"}}}}},"security":[{"APIKeyHeader":[]}]},"post":{"summary":"Categorize Product","operationId":"categorize_product_categorizations_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductQuery"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"402":{"description":"Payment required: the body carries the x402 payment requirements"},"409":{"description":"The payment proof has already been used"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/health":{"get":{"tags":["service"],"summary":"Liveness: does the process answer?","description":"Nessun I/O: risponde finche' il processo e' in grado di rispondere.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/health/ready":{"get":{"tags":["service"],"summary":"Readiness: do the dependencies answer?","description":"Verifica Postgres e Redis, riportando l'esito per componente.\n\nUn singolo booleano costringerebbe a leggere i log per sapere quale delle\ndue dipendenze e' giu'.","operationId":"ready_health_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ready Health Ready Get"}}}}}}}},"components":{"schemas":{"CategoryMatch":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Id","description":"Category identifier in the target taxonomy"},"category":{"type":"string","title":"Category","description":"Category name as it appears in the taxonomy"},"reason":{"type":"string","title":"Reason","description":"Why the model picked this category"},"level":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Level","description":"Zero-based depth in the taxonomy tree; null on legacy records"},"truncated":{"type":"boolean","title":"Truncated","description":"True on the last match when the per-request token budget stopped the descent: the path is valid but not necessarily a leaf","default":false}},"type":"object","required":["category","reason"],"title":"CategoryMatch","description":"One level of the taxonomy descent: the category matched at that depth."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Product":{"properties":{"name":{"type":"string","title":"Name","description":"Product name"},"categories":{"items":{"$ref":"#/components/schemas/CategoryMatch"},"type":"array","title":"Categories","description":"One match per taxonomy level, from broadest to most specific. The last item may carry truncated=true"},"judge_approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Judge Approved","description":"Whether a separate LLM judge confirmed the final category path is consistent with the description; null when the token budget ran out before the judge could run"},"judge_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Judge Reason","description":"The judge's stated reason for its verdict on the final path; null when the judge did not run or the final path was never judged"}},"type":"object","required":["name","categories"],"title":"Product"},"ProductCategorizationOut":{"properties":{"id":{"type":"integer","title":"Id"},"product_name":{"type":"string","title":"Product Name"},"categories":{"items":{"$ref":"#/components/schemas/CategoryMatch"},"type":"array","title":"Categories"},"store_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Store Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"feedback_rating":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Feedback Rating"}},"type":"object","required":["id","product_name","categories","created_at"],"title":"ProductCategorizationOut"},"ProductQuery":{"properties":{"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description","description":"Product description to categorize"},"store_id":{"type":"string","enum":["amazon.com","amazon.it","amazon.co.uk","ebay.com","ebay.it","ebay.co.uk","shopify.com","en-US"],"title":"Store Id","description":"The store to categorize the product in"}},"type":"object","required":["description","store_id"],"title":"ProductQuery"},"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":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}