{"openapi":"3.1.0","info":{"title":"HSN Code Finder API","version":"1.0.0","summary":"Free, public HSN/SAC lookup API. No API key, no signup. Backed by the CBIC GST schedule.","description":"Forward lookup (description → HSN/SAC code) and reverse lookup (code → description) against a bundled snapshot of India's CBIC GST tariff. Treat this as a goodwill resource — please cache aggressively (responses are valid for ~1 week) and avoid sustained bursts above 10 req/s. Source: https://cbic-gst.gov.in/gst-goods-services-rates.html (snapshot 2025-10-01).","contact":{"name":"Krake Labs India","url":"https://krakelabsindia.com"},"license":{"name":"Best-effort free service","url":"https://hsn.krakelabsindia.com/developers"}},"servers":[{"url":"https://hsn.krakelabsindia.com","description":"Production"}],"tags":[{"name":"Lookup","description":"Forward & reverse HSN/SAC lookup"},{"name":"Meta","description":"Dataset metadata"}],"paths":{"/api/lookup":{"get":{"tags":["Lookup"],"summary":"Forward or reverse HSN/SAC lookup","description":"Provide `q` for a text description lookup, or `code` for a reverse code lookup. Exactly one of `q` or `code` is required.","parameters":[{"name":"q","in":"query","required":false,"description":"Text description, e.g. 'cotton t-shirt' or 'cab service'.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"cotton t-shirt"},{"name":"code","in":"query","required":false,"description":"HSN or SAC code (full or prefix), e.g. '8517' or '85'.","schema":{"type":"string","minLength":1,"maxLength":20},"example":"8517"},{"name":"limit","in":"query","required":false,"description":"Max number of matches returned for `?q=` lookups (1-20, default 5). Ignored for `?code=`.","schema":{"type":"integer","minimum":1,"maximum":20,"default":5},"example":5}],"responses":{"200":{"description":"Successful lookup","headers":{"Cache-Control":{"description":"Edge cache hint — dataset changes weekly.","schema":{"type":"string","example":"public, max-age=3600"}},"Access-Control-Allow-Origin":{"description":"CORS — open to all origins.","schema":{"type":"string","example":"*"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ForwardLookupResponse"},{"$ref":"#/components/schemas/ReverseLookupResponse"}]}}}},"400":{"description":"Missing or invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (per-IP, ~20 req/min)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Lookup"],"summary":"Batch forward lookup","description":"Submit up to 10 description strings; returns the single best HSN/SAC match for each. Use the GET endpoint for single-item queries — it caches better.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchLookupRequest"},"example":{"items":["cotton t-shirt","cab service"]}}}},"responses":{"200":{"description":"Successful batch lookup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchLookupResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/meta":{"get":{"tags":["Meta"],"summary":"Dataset metadata","description":"Returns counts and snapshot date for the bundled CBIC HSN/SAC dataset.","responses":{"200":{"description":"Dataset metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetMeta"}}}}}}}},"components":{"schemas":{"HsnResult":{"type":"object","description":"A single HSN/SAC match.","required":["description","hsn_sac","chapter","gst_rate","type","notes"],"properties":{"description":{"type":"string","description":"Canonical description of the matched code.","example":"T-shirts, singlets and other vests, knitted or crocheted"},"hsn_sac":{"type":"string","description":"The HSN (goods) or SAC (services) code.","example":"6109"},"chapter":{"type":"string","description":"Chapter heading for context.","example":"Articles of apparel and clothing accessories, knitted or crocheted"},"gst_rate":{"type":"string","description":"Applicable GST rate as published in the CBIC schedule.","example":"12%"},"type":{"type":"string","enum":["goods","services"],"description":"Whether this is HSN (goods) or SAC (services)."},"notes":{"type":"string","description":"Caveats, sub-rates, or schedule notes.","example":"Of cotton — 5% if sale value below ₹1000 per piece"},"why":{"type":"string","description":"Human-readable explanation of why this code matched.","example":"Matched on 'cotton' and 't-shirt' from the cotton apparel keyword set"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Match confidence (0-1). Low values mean we're guessing.","example":0.82},"cess_rate":{"type":"number","description":"GST Compensation Cess rate as a percentage. Present only for cess-bearing codes (tobacco, autos, aerated drinks, coal). For coal/lignite the cess is specific (₹/tonne) — see cess_note.","example":12},"cess_note":{"type":"string","description":"Caveats about the cess: slab, specific-rate component, or amendment.","example":"12% compensation cess on aerated/carbonated waters with added sugar."},"rcm_applicable":{"type":"boolean","description":"True when reverse charge applies on this supply (recipient pays GST). Cross-check Notification 13/2017-CT(R).","example":true},"rcm_trigger":{"type":"string","description":"Plain-language trigger for the RCM (supplier type / recipient type).","example":"Legal services supplied by an advocate to a business entity → recipient pays GST."},"uqc":{"type":"string","description":"Unique Quantity Code for invoices / GSTR-1. Common values: NOS, KGS, MTR, SQM, LTR, PCS, TON, GMS, MWT, DOZ, UNT.","example":"NOS"},"notification_ref":{"type":"string","description":"CBIC notification reference where this rate sits.","example":"1/2017-CT(R) Schedule III"},"effective_from":{"type":"string","format":"date","description":"ISO date this rate became effective.","example":"2017-07-01"},"section":{"type":"string","description":"Roman-numeral HS section (I-XXIII) for chapter-tree navigation.","example":"XI"},"schedule":{"type":"string","description":"Notification 1/2017 schedule label, e.g. 'III (18%)' or 'Exempt'.","example":"I (5%)"}}},"ForwardLookupResponse":{"type":"object","required":["query","matches"],"properties":{"query":{"type":"string","example":"cotton t-shirt"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/HsnResult"}}}},"ReverseLookupResponse":{"type":"object","required":["query","results"],"properties":{"query":{"type":"string","example":"8517"},"results":{"type":"array","items":{"$ref":"#/components/schemas/HsnResult"}}}},"BatchLookupRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","minLength":1,"maxLength":200},"description":"1-10 description strings to look up."}}},"BatchLookupResponse":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/HsnResult"},{"type":"object","properties":{"alternates":{"type":"array","description":"Up to 2 alternate candidate matches.","items":{"$ref":"#/components/schemas/HsnResult"}}}}]}}}},"DatasetMeta":{"type":"object","required":["totalCodes","goodsCount","servicesCount","asOf","sourceUrl"],"properties":{"totalCodes":{"type":"integer","example":1743},"goodsCount":{"type":"integer","example":1620},"servicesCount":{"type":"integer","example":123},"asOf":{"type":"string","description":"ISO date of the dataset snapshot.","example":"2025-10-01"},"sourceUrl":{"type":"string","format":"uri","example":"https://cbic-gst.gov.in/gst-goods-services-rates.html"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"Missing required query param 'q'"}}}}}}