{"openapi":"3.1.0","info":{"title":"hts-classify","version":"0.1.0","description":"Classify a product description into candidate HS/HTS10 tariff codes. Deterministic BM25 retrieval over the USITC HTS schedule with heading-agreement boosting, returning the full parent-chain description, general duty rate, and a score-gap confidence per candidate. Not a customs ruling — always includes a disclaimer to verify with a licensed broker.; Classify up to 100 product descriptions in one paid call — one payment covers the whole batch (per-item discount vs calling `classify` N times). Deterministic BM25 retrieval over the USITC HTS schedule, same as `classify`. Not a customs ruling — always includes a disclaimer to verify with a licensed broker.","x-guidance":"Call `classify` with `description`: a short plain-text product description (max 500 characters). Optionally set `options.top_k` (1..10 candidates, default 3) and `options.origin_hint` (country/region of origin, accepted but not yet used in scoring). Returns `candidates` ranked by score-gap confidence — each with the full HTS10 code, its parent-chain description path, and the general (MFN) duty rate — plus a `disclaimer`. This is a classification aid, not a binding customs ruling; always surface the disclaimer to the end user and recommend verifying with a licensed customs broker before filing.","contact":{"email":"jeff@fosterinstruments.com"}},"servers":[{"url":"https://hts-classify.x402supply.com"}],"paths":{"/mcp":{"post":{"operationId":"hts-classify_call","summary":"Call hts-classify via MCP tools/call","tags":["hts-classify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["jsonrpc","id","method","params"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"method":{"const":"tools/call"},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"const":"classify"},"arguments":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":500},"options":{"type":"object","properties":{"top_k":{"type":"integer","minimum":1,"maximum":10,"default":3},"origin_hint":{"type":"string","maxLength":100}},"additionalProperties":false}},"required":["description"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}},{"type":"object","required":["jsonrpc","id","method","params"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"method":{"const":"tools/call"},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"const":"classify_bulk"},"arguments":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"minItems":1,"maxItems":100},"options":{"type":"object","properties":{"top_k":{"type":"integer","minimum":1,"maximum":10,"default":3},"origin_hint":{"type":"string","maxLength":100}},"additionalProperties":false}},"required":["items"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}]}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"JSON-RPC 2.0 response envelope. `result.content[0].text` is a JSON-encoded string matching the schema in `x-mcp-result-schema`.","properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"result":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"const":"text"},"text":{"type":"string"}}}}}}},"x-mcp-result-schema":{"type":"object","required":["candidates","disclaimer"],"properties":{"candidates":{"type":"array","items":{"type":"object","required":["hts10","hs6","description_path","duty_general","confidence","reasoning_short"],"properties":{"hts10":{"type":"string"},"hs6":{"type":"string"},"description_path":{"type":"string"},"duty_general":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning_short":{"type":"string"}}}},"disclaimer":{"type":"string"}}}},{"type":"object","description":"JSON-RPC 2.0 response envelope. `result.content[0].text` is a JSON-encoded string matching the schema in `x-mcp-result-schema`.","properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"result":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"const":"text"},"text":{"type":"string"}}}}}}},"x-mcp-result-schema":{"type":"object","required":["results","disclaimer"],"properties":{"results":{"type":"array","items":{"type":"object","required":["index","candidates"],"properties":{"index":{"type":"integer"},"candidates":{"type":"array","items":{"type":"object","required":["hts10","hs6","description_path","duty_general","confidence","reasoning_short"],"properties":{"hts10":{"type":"string"},"hs6":{"type":"string"},"description_path":{"type":"string"},"duty_general":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning_short":{"type":"string"}}}}}}},"disclaimer":{"type":"string"}}}}]}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"accepts":{"type":"array"}}}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.10"},"protocols":[{"x402":{}}]}}},"/tools/classify":{"post":{"operationId":"hts-classify_classify_http","summary":"Classify a product description into candidate HS/HTS10 tariff codes. Deterministic BM25 retrieval over the USITC HTS schedule with heading-agreement boosting, returning the full parent-chain description, general duty rate, and a score-gap confidence per candidate. Not a customs ruling — always includes a disclaimer to verify with a licensed broker.","tags":["hts-classify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":500},"options":{"type":"object","properties":{"top_k":{"type":"integer","minimum":1,"maximum":10,"default":3},"origin_hint":{"type":"string","maxLength":100}},"additionalProperties":false}},"required":["description"],"additionalProperties":false},"example":{"description":"men's knitted cotton t-shirt","options":{"top_k":2}}}}},"responses":{"200":{"description":"Tool result (plain JSON, not MCP-wrapped)","content":{"application/json":{"schema":{"type":"object","required":["candidates","disclaimer"],"properties":{"candidates":{"type":"array","items":{"type":"object","required":["hts10","hs6","description_path","duty_general","confidence","reasoning_short"],"properties":{"hts10":{"type":"string"},"hs6":{"type":"string"},"description_path":{"type":"string"},"duty_general":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning_short":{"type":"string"}}}},"disclaimer":{"type":"string"}}},"example":{"candidates":[{"hts10":"6109.10.00.12","hs6":"6109.10","description_path":"T-shirts, singlets, tank tops and similar garments, knitted or crocheted: > Of cotton > Men's or boys': > Other T-shirts: > Men's (338)","duty_general":"","confidence":0.95,"reasoning_short":"Matched terms [men, s, knitted, cotton, t, shirt] against \"Men's (338)\" (HS6 6109.10)."},{"hts10":"6109.10.00.14","hs6":"6109.10","description_path":"T-shirts, singlets, tank tops and similar garments, knitted or crocheted: > Of cotton > Men's or boys': > Other T-shirts: > Boys' (338)","duty_general":"","confidence":0.915,"reasoning_short":"Matched terms [men, s, knitted, cotton, t, shirt] against \"Boys' (338)\" (HS6 6109.10)."}],"disclaimer":"Informational classification aid — not a customs ruling. Verify with a licensed customs broker for binding classification."}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"accepts":{"type":"array"}}}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.10"},"protocols":[{"x402":{}}]}}},"/tools/classify_bulk":{"post":{"operationId":"hts-classify_classify_bulk_http","summary":"Classify up to 100 product descriptions in one paid call — one payment covers the whole batch (per-item discount vs calling `classify` N times). Deterministic BM25 retrieval over the USITC HTS schedule, same as `classify`. Not a customs ruling — always includes a disclaimer to verify with a licensed broker.","tags":["hts-classify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"minItems":1,"maxItems":100},"options":{"type":"object","properties":{"top_k":{"type":"integer","minimum":1,"maximum":10,"default":3},"origin_hint":{"type":"string","maxLength":100}},"additionalProperties":false}},"required":["items"],"additionalProperties":false},"example":{"items":["cotton t-shirt, knitted, mens","lithium ion battery pack for laptops"],"options":{"top_k":1}}}}},"responses":{"200":{"description":"Tool result (plain JSON, not MCP-wrapped)","content":{"application/json":{"schema":{"type":"object","required":["results","disclaimer"],"properties":{"results":{"type":"array","items":{"type":"object","required":["index","candidates"],"properties":{"index":{"type":"integer"},"candidates":{"type":"array","items":{"type":"object","required":["hts10","hs6","description_path","duty_general","confidence","reasoning_short"],"properties":{"hts10":{"type":"string"},"hs6":{"type":"string"},"description_path":{"type":"string"},"duty_general":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning_short":{"type":"string"}}}}}}},"disclaimer":{"type":"string"}}},"example":{"results":[{"index":0,"candidates":[{"hts10":"6109.10.00.12","hs6":"6109.10","description_path":"T-shirts, singlets, tank tops and similar garments, knitted or crocheted: > Of cotton > Men's or boys': > Other T-shirts: > Men's (338)","duty_general":"","confidence":0.95,"reasoning_short":"Matched terms [cotton, t, shirt, knitted, men] against \"Men's (338)\" (HS6 6109.10)."}]},{"index":1,"candidates":[{"hts10":"8507.60.00.90","hs6":"8507.60","description_path":"Electric storage batteries, including separators therefor, whether or not rectangular (including square); parts thereof: > Lithium-ion batteries > Other: > Other","duty_general":"","confidence":0.95,"reasoning_short":"Matched terms [lithium, ion, battery] against \"Other\" (HS6 8507.60)."}]}],"disclaimer":"Informational classification aid — not a customs ruling. Verify with a licensed customs broker for binding classification."}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"accepts":{"type":"array"}}}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.10"},"protocols":[{"x402":{}}]}}}}}