HempData API API

{"openapi":"3.1.0","info":{"title":"HempData API","version":"1.0.0","description":"Structured hemp and cannabis regulatory data for all 50 US states plus Washington DC. Machine-readable compliance information including legal status, THC/CBD limits, labeling requirements, testing standards, shipping rules, and enforcement details — updated continuously and verified by legal analysts.","contact":{"name":"HempData API Support","url":"https://hempdata.io","email":"hello@hempdata.io"}},"servers":[{"url":"https://api.hempdata.io","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Pass your key in the Authorization header as: Bearer hda_live_sk_..."}},"schemas":{"Regulation":{"type":"object","description":"A single hemp regulation record for a specific jurisdiction, substance, and product type combination.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Unique regulation record identifier Null on a canon row (source: \"canon\")."},"jurisdiction":{"type":"string","description":"Two-letter state code or DC","example":"CO"},"substance":{"type":"string","description":"Regulated substance name","example":"delta-9-thc"},"product_type":{"type":"string","description":"Product type category","example":"edibles"},"legal_status":{"type":"string","enum":["legal","restricted","prohibited","gray_area","pending_change"],"description":"Current legal status in this jurisdiction"},"federal_status":{"type":"string","description":"Federal legal status for this substance/product combination","example":"legal_under_farm_bill"},"thc_limit_pct_dryweight":{"type":["number","null"],"description":"Maximum THC concentration as percentage of dry weight","example":0.3},"thc_limit_mg_per_serving":{"type":["number","null"],"description":"Maximum THC in milligrams per serving","example":10},"thc_limit_mg_per_container":{"type":["number","null"],"description":"Maximum THC in milligrams per container/package","example":100},"thc_measurement_method":{"type":["string","null"],"description":"Required method for measuring THC content (e.g. post-decarboxylation, total THC)","example":"post-decarboxylation"},"cbd_limit_mg_per_serving":{"type":["number","null"],"description":"Maximum CBD in milligrams per serving, if regulated"},"age_restriction":{"type":["integer","null"],"description":"Minimum age for purchase","example":21},"age_verification_method":{"type":["string","null"],"description":"Required age verification method (e.g. id_scan, self_attestation)","example":"id_scan"},"labeling_required":{"type":["boolean","null"],"description":"Whether specific labeling is mandated"},"warning_text_verbatim":{"type":["string","null"],"description":"Exact warning text required on packaging, if any"},"testing_standard":{"type":["string","null"],"description":"Required testing standard or accreditation (e.g. ISO 17025)"},"testing_panels_required":{"type":["array","null"],"items":{"type":"string"},"description":"List of required testing panels (e.g. potency, pesticides, heavy_metals, microbials)","example":["potency","pesticides","heavy_metals","residual_solvents","microbials"]},"shipping_status":{"type":["string","null"],"description":"Whether the product can be shipped to/from this state","example":"allowed"},"carrier_restrictions":{"type":["array","null"],"items":{"type":"string"},"description":"Carriers that restrict or prohibit shipping this product","example":["usps"]},"license_required":{"type":["boolean","null"],"description":"Whether a state license is required to sell"},"license_type":{"type":["string","null"],"description":"Type of license required (e.g. hemp_processor, retail_cannabis)","example":"hemp_processor"},"enforcement_date":{"type":["string","null"],"format":"date","description":"Date the regulation took or takes effect"},"enforcement_agency":{"type":["string","null"],"description":"Government agency responsible for enforcement","example":"Colorado Department of Agriculture"},"penalty_range":{"type":["string","null"],"description":"Summary of penalties for non-compliance","example":"$500-$10,000 fine; possible license revocation"},"source_urls":{"type":["array","null"],"items":{"type":"string","format":"uri"},"description":"URLs to official source documents"},"source_documents":{"type":["array","null"],"items":{"type":"string"},"description":"Names or references of source documents"},"plain_english":{"type":["string","null"],"description":"Human-readable summary of the regulation","example":"Delta-9 THC edibles are legal in Colorado for adults 21+ with per-serving and per-package limits."},"block_sale":{"type":["boolean","null"],"description":"Whether sales should be blocked in this jurisdiction (compliance recommendation)"},"effective_date":{"type":["string","null"],"format":"date","description":"Date the regulation became effective"},"expiry_date":{"type":["string","null"],"format":"date","description":"Date the regulation expires or sunsets, if applicable"},"related_bills":{"type":["array","null"],"items":{"type":"object","properties":{"bill_id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"url":{"type":"string","format":"uri"}}},"description":"Related legislative bills"},"last_verified":{"type":"string","format":"date-time","description":"When this regulation was last verified by a human analyst"},"verification_tier":{"type":"string","enum":["attorney_reviewed","analyst_verified","automated","unverified"],"description":"Level of human verification applied"},"confidence_score":{"type":"number","minimum":0,"maximum":1,"description":"Confidence score from 0 to 1 indicating data reliability","example":0.95},"legal_status_source":{"type":"string","enum":["canon_overlay","db"],"description":"canon_overlay = the canonical substance verdict raised the stored status (a row is never served less strict than canon); db = the stored value stands (not a claim of human review)."},"prose_source":{"type":"string","enum":["canon"],"description":"Present when the narrative fields (plain_english / summary / summary_140_chars / summary_paragraph) were replaced by the canonical verdict line + verbatim rule basis + fact id, because the canonical verdict decided this row and the stored text contradicted it."},"source":{"type":"string","enum":["canon"],"description":"Present only on a row assembled at read time from HempData's verified facts because the regulations table has no row for this state + substance. Such a row has id null, is a substance-level verdict (product-form rules are not evaluated — see state_rule) and is never written to the table."},"canon_fact_id":{"type":["string","null"],"description":"The verified fact id behind a canon verdict / canon prose."},"canon_verdict":{"type":"string","description":"The verdict line /v1/answer prints for this state + substance (canon rows only)."},"canon_scope":{"type":"string","enum":["substance_level"],"description":"Canon rows answer for the substance; product-form rules are in state_rule, not evaluated."},"state_rule":{"type":["string","null"],"description":"The state's verified fact (canonical phrasing), verbatim."},"canon_form_note":{"type":"string","description":"Set when a product-form rule in the state's fact (e.g. beverage-specific limits) is not evaluated by a substance-level canon row; the row is then served 'restricted', never 'legal'."},"canon_verdict_source":{"type":"string","enum":["canon","fallback_map","unsettled"],"description":"How the canonical verdict reached the status on a canon row: canon = a verified fact settles it; fallback_map = HempData's audited prohibition review; unsettled = the canon declines to settle it (served gray_area — not permission)."}},"required":["id","jurisdiction","substance","product_type","legal_status","confidence_score","last_verified","verification_tier"]},"ChangelogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"regulation_id":{"type":"string","format":"uuid"},"jurisdiction":{"type":"string"},"field_changed":{"type":"string"},"old_value":{},"new_value":{},"changed_at":{"type":"string","format":"date-time"},"reason":{"type":"string"}}},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"total":{"type":"integer","example":142},"total_pages":{"type":"integer","example":6}},"required":["page","per_page","total","total_pages"]},"PaginatedRegulationResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Regulation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data","meta"]},"PaginatedChangelogResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data","meta"]},"ApiResponse_Regulation":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Regulation"},"meta":{"type":"object"},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"ApiResponse_Comparison":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Comparison results keyed by state code","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/Regulation"}}},"meta":{"type":"object","properties":{"states_compared":{"type":"array","items":{"type":"string"}},"substance_filter":{"type":["string","null"]},"product_type_filter":{"type":["string","null"]}}},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"StateSummary":{"type":"object","properties":{"code":{"type":"string","description":"Two-letter state code","example":"CO"},"name":{"type":"string","example":"Colorado"},"regulation_count":{"type":"integer","description":"Number of regulation records for this state"},"overall_stance":{"type":"string","enum":["permissive","moderate","restrictive","prohibitive"],"description":"General regulatory stance toward hemp products"},"last_updated":{"type":"string","format":"date-time"}},"required":["code","name","regulation_count","overall_stance","last_updated"]},"StateProfile":{"type":"object","properties":{"code":{"type":"string","example":"CO"},"name":{"type":"string","example":"Colorado"},"overall_stance":{"type":"string","enum":["permissive","moderate","restrictive","prohibitive"]},"regulation_count":{"type":"integer"},"regulations":{"type":"array","items":{"$ref":"#/components/schemas/Regulation"}},"regulatory_agency":{"type":"string","example":"Colorado Department of Agriculture"},"hemp_program_url":{"type":["string","null"],"format":"uri"},"notes":{"type":["string","null"]},"last_updated":{"type":"string","format":"date-time"}},"required":["code","name","overall_stance","regulation_count","regulations","last_updated"]},"ApiResponse_StateList":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/StateSummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer","example":51}}},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"ApiResponse_StateProfile":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/StateProfile"},"meta":{"type":"object"},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"SubstanceSummary":{"type":"object","properties":{"slug":{"type":"string","example":"delta-9-thc"},"name":{"type":"string","example":"Delta-9 THC"},"description":{"type":"string"},"regulation_count":{"type":"integer"},"states_legal":{"type":"integer","description":"Number of states where this substance is legal"},"states_restricted":{"type":"integer"},"states_prohibited":{"type":"integer"},"aliases":{"type":"array","items":{"type":"string"},"description":"Other spellings merged into this entry. Every slug and alias is accepted by the /v1/regulations filters (one normalizer)."}},"required":["slug","name","regulation_count"]},"ApiResponse_SubstanceList":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/SubstanceSummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"ProductTypeSummary":{"type":"object","properties":{"slug":{"type":"string","example":"edibles"},"name":{"type":"string","example":"Edibles"},"description":{"type":"string"},"regulation_count":{"type":"integer"},"aliases":{"type":"array","items":{"type":"string"},"description":"Other spellings merged into this entry. Every slug and alias is accepted by the /v1/regulations filters (one normalizer)."}},"required":["slug","name","regulation_count"]},"ApiResponse_ProductTypeList":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeSummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"WebhookCreateRequest":{"type":"object","properties":{"endpoint_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook payloads","example":"https://example.com/webhooks/hempdata"},"filters":{"type":"object","properties":{"jurisdictions":{"type":"array","items":{"type":"string"},"description":"State codes to filter events (empty = all states)","example":["CO","CA","NY"]},"substances":{"type":"array","items":{"type":"string"},"description":"Substances to filter events","example":["delta-9-thc","delta-8-thc"]},"events":{"type":"array","items":{"type":"string","enum":["regulation.created","regulation.updated","regulation.status_changed","regulation.expiring"]},"description":"Event types to subscribe to","example":["regulation.updated","regulation.status_changed"]}}}},"required":["endpoint_url"]},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"endpoint_url":{"type":"string","format":"uri"},"filters":{"type":"object","properties":{"jurisdictions":{"type":"array","items":{"type":"string"}},"substances":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"type":"string"}}}},"signing_secret":{"type":"string","description":"HMAC secret for verifying webhook payloads","example":"whsec_..."},"status":{"type":"string","enum":["active","paused","failed"],"example":"active"},"created_at":{"type":"string","format":"date-time"}},"required":["id","endpoint_url","signing_secret","status","created_at"]},"WebhookPayload":{"type":"object","description":"Payload delivered to webhook endpoints when regulation events occur.","properties":{"event_id":{"type":"string","format":"uuid"},"event_type":{"type":"string","enum":["regulation.created","regulation.updated","regulation.status_changed","regulation.expiring"]},"timestamp":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"regulation":{"$ref":"#/components/schemas/Regulation"},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"old_value":{},"new_value":{}}}}}}},"required":["event_id","event_type","timestamp","data"]},"ApiResponse_Webhook":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/WebhookSubscription"},"meta":{"type":"object"},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"ApiResponse_WebhookList":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"WidgetCheckRequest":{"type":"object","properties":{"api_key":{"type":"string","description":"API key for widget authentication","example":"hda_live_sk_..."},"substance":{"type":"string","description":"Substance to check","example":"delta-9-thc"},"product_type":{"type":"string","description":"Product type to check","example":"edibles"},"state":{"type":"string","description":"Two-letter state code (provide this or ip)","example":"CO"},"ip":{"type":"string","description":"IP address for geo-lookup (provide this or state)","example":"24.130.45.67"}},"required":["api_key","substance","product_type"]},"WidgetCheckResult":{"type":"object","properties":{"allowed":{"type":"boolean","description":"Whether the product can be sold in this jurisdiction"},"jurisdiction":{"type":"string","example":"CO"},"legal_status":{"type":"string","enum":["legal","restricted","prohibited","gray_area","pending_change"]},"block_sale":{"type":"boolean"},"age_restriction":{"type":["integer","null"]},"warning_text":{"type":["string","null"],"description":"Required warning text to display, if any"},"plain_english":{"type":["string","null"],"description":"Human-readable summary"},"confidence_score":{"type":"number"},"last_verified":{"type":"string","format":"date-time"}},"required":["allowed","jurisdiction","legal_status","block_sale","confidence_score","last_verified"]},"ApiResponse_WidgetCheck":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/WidgetCheckResult"},"meta":{"type":"object"},"errors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","data"]},"ApiError":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","example":"INVALID_STATE_CODE"},"message":{"type":"string","description":"Human-readable error message","example":"Invalid state code: XX"},"field":{"type":["string","null"],"description":"Field that caused the error, if applicable"}},"required":["code","message"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"data":{"type":"null"},"meta":{"type":"object"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}},"required":["success","errors"]},"ComplianceSource":{"type":"object","description":"One provenance entry backing a compliance answer. Never invented: empty source data in the record yields an empty array, not fabricated citations.","properties":{"type":{"type":"string","enum":["federal_law","federal_rule","state_statute","agency_rule","case_law","bill_pending","fda_action","carrier_policy"]},"citation":{"type":"string"},"publisher":{"type":"string"},"url":{"type":["string","null"]},"retrieved_at":{"type":["string","null"],"format":"date-time"},"license":{"type":"string"},"confidence":{"type":["number","null"]},"attorney_reviewed":{"type":"boolean"}},"required":["type","citation","publisher"]},"ComplianceVerification":{"type":"object","description":"How this answer traces to canonical, human-reviewed verified data. status=verified means the jurisdiction carries a canonical posture fact (statute-cited, primary-sourced). Treat unverified figures as orientation, not a compliance decision.","properties":{"status":{"type":"string","enum":["verified","unverified"]},"fact_id":{"type":["string","null"],"description":"Canonical fact id (matches docs/REGULATORY_FACTS.md heading)"},"statute":{"type":["string","null"],"description":"Statute citation backing the jurisdiction's verified posture"},"last_verified":{"type":["string","null"],"description":"ISO date of the most recent human verification against primary sources"},"primary_sources":{"type":"array","items":{"type":"string"},"description":"Primary-source URLs grounding the fact"},"thc_limit_source":{"type":"string","enum":["verified","db"],"description":"verified = mg caps reconciled against the canonical verified state limits"},"legal_status_source":{"type":"string","enum":["canon_overlay","db"],"description":"canon_overlay = legal status raised by the canonical verdict / prohibition map; db = the stored value stands"}},"required":["status","thc_limit_source","legal_status_source","primary_sources"]},"ComplianceCheckResult":{"type":"object","properties":{"state":{"type":"string","description":"Two-letter jurisdiction code"},"state_name":{"type":["string","null"]},"substance":{"type":"string"},"product_type":{"type":"string"},"legal_status":{"type":"string","enum":["legal","legal_with_restrictions","gray_area","prohibited","unknown"],"description":"'unknown' is returned only when no regulation row matches AND the substance is not one the canonical verdict names. When the canon settles the state + substance it answers (source: \"canon\"); when the canon is unsettled on it the answer is gray_area with the canon's own not-settled line."},"effective_status":{"type":["string","null"],"description":"Status after applying the federal H.R. 5371 timeline overlay"},"summary":{"type":["string","null"]},"confidence_score":{"type":["number","null"],"description":"0..1 — always a JSON number, never a string"},"last_verified":{"type":["string","null"],"format":"date-time"},"thc_limit_pct_dryweight":{"type":["number","null"]},"thc_limit_mg_per_serving":{"type":["number","null"]},"thc_limit_mg_per_container":{"type":["number","null"]},"age_restriction":{"type":["number","null"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ComplianceSource"}},"verification":{"$ref":"#/components/schemas/ComplianceVerification"},"disclaimer":{"type":"string"},"attribution":{"type":"string"},"legal_status_source":{"type":"string","enum":["canon_overlay","db"],"description":"canon_overlay = the canonical substance verdict raised the stored status (a row is never served less strict than canon); db = the stored value stands (not a claim of human review)."},"prose_source":{"type":"string","enum":["canon"],"description":"Present when the narrative fields (plain_english / summary / summary_140_chars / summary_paragraph) were replaced by the canonical verdict line + verbatim rule basis + fact id, because the canonical verdict decided this row and the stored text contradicted it."},"source":{"type":"string","enum":["canon"],"description":"Present only on a row assembled at read time from HempData's verified facts because the regulations table has no row for this state + substance. Such a row has id null, is a substance-level verdict (product-form rules are not evaluated — see state_rule) and is never written to the table."},"canon_fact_id":{"type":["string","null"],"description":"The verified fact id behind a canon verdict / canon prose."},"canon_verdict":{"type":"string","description":"The verdict line /v1/answer prints for this state + substance (canon rows only)."},"canon_scope":{"type":"string","enum":["substance_level"],"description":"Canon rows answer for the substance; product-form rules are in state_rule, not evaluated."},"state_rule":{"type":["string","null"],"description":"The state's verified fact (canonical phrasing), verbatim."},"canon_form_note":{"type":"string","description":"Set when a product-form rule in the state's fact (e.g. beverage-specific limits) is not evaluated by a substance-level canon row; the row is then served 'restricted', never 'legal'."},"canon_verdict_source":{"type":"string","enum":["canon","fallback_map","unsettled"],"description":"How the canonical verdict reached the status on a canon row: canon = a verified fact settles it; fallback_map = HempData's audited prohibition review; unsettled = the canon declines to settle it (served gray_area — not permission)."}},"required":["state","substance","product_type","legal_status","sources","disclaimer"]},"ApiResponse_ComplianceCheck":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ComplianceCheckResult"},"meta":{"type":["object","null"]},"errors":{"type":"null"}},"required":["success","data"]},"AnswerCitation":{"type":"object","properties":{"n":{"type":"integer","description":"1-based index matching the inline [n] marker in the answer text"},"label":{"type":"string"},"url":{"type":"string"}},"required":["n","label","url"]},"AnswerVerification":{"type":"object","description":"Verification backing the answer. status=verified means the figure traces to a tracked, human-reviewed fact with primary sources.","properties":{"status":{"type":"string","enum":["verified","unverified"]},"confidence":{"type":"number"},"factId":{"type":"string"},"statute":{"type":"string"},"lastVerified":{"type":"string"},"primarySources":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string","description":"Present only when status=unverified"}},"required":["status","confidence"]},"AnswerResult":{"type":"object","description":"Deterministic Verified Answer Engine result. status=answered carries a citation-backed answer; status=gap is an honest refusal (still HTTP 200) when verified data can't answer.","properties":{"status":{"type":"string","enum":["answered","gap"]},"intent":{"type":"string"},"parsed":{"type":"object","description":"What the deterministic parser extracted (states, substance, numbers, trace)"},"answer":{"type":"object","properties":{"text":{"type":"string","description":"Answer text with inline [n] citation markers"},"citations":{"type":"array","items":{"$ref":"#/components/schemas/AnswerCitation"}},"verification":{"$ref":"#/components/schemas/AnswerVerification"},"data":{"description":"Raw verified tool output for structured consumers"}},"required":["text","citations","verification"]},"gap":{"type":"object","properties":{"reason":{"type":"string"},"missing":{"type":"string","description":"Human-facing description of what's missing / how to rephrase"},"states":{"type":"array","items":{"type":"string"}},"substance":{"type":["string","null"]},"product_type":{"type":["string","null"]}}}},"required":["status","intent"]},"ApiResponse_Answer":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AnswerResult"},"meta":{"type":["object","null"]},"errors":{"type":"null"}},"required":["success","data"]},"ComplianceScanRequest":{"type":"object","description":"COA numbers for a finished product. All potency fields are percentages from the certificate of analysis.","properties":{"total_thc_percent":{"type":"number","minimum":0,"maximum":100},"delta9_thc_percent":{"type":"number","minimum":0,"maximum":100},"thca_percent":{"type":"number","minimum":0,"maximum":100},"substance":{"type":"string"},"product_type":{"type":"string"},"serving_size_mg":{"type":"number","exclusiveMinimum":0},"servings_per_container":{"type":"integer","minimum":1}},"required":["total_thc_percent","delta9_thc_percent","thca_percent","product_type","serving_size_mg","servings_per_container"]},"ComplianceReformulateRequest":{"type":"object","properties":{"current_formulation":{"type":"object","properties":{"thc_per_serving_mg":{"type":"number","minimum":0},"servings_per_container":{"type":"integer","minimum":1},"total_thc_mg":{"type":"number","minimum":0},"product_type":{"type":"string"}},"required":["thc_per_serving_mg","servings_per_container","total_thc_mg","product_type"]},"target_states":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"minItems":1,"maxItems":56},"save_request":{"type":"boolean","default":false}},"required":["current_formulation","target_states"]},"FreeKeyRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"ApiResponse_FreeKey":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"subscriber_id":{"type":"string"},"plan":{"type":"string","enum":["free"]},"tier":{"type":"string","description":"Always \"free\" for new keys; kept for client compatibility"},"api_key":{"type":"string","description":"Secret key (hda_live_sk_...) — shown once, store it now"},"publishable_key":{"type":"string","description":"Publishable key (hda_live_pk_...) for the embeddable widget"},"message":{"type":"string"}},"required":["subscriber_id","tier","api_key","publishable_key"]},"meta":{"type":["object","null"]},"errors":{"type":"null"}},"required":["success","data"]}}},"tags":[{"name":"Status","description":"API health and version"},{"name":"Regulations","description":"Query, compare, and track hemp regulation data"},{"name":"States","description":"State summaries and detailed profiles"},{"name":"Substances","description":"Tracked hemp-derived substances"},{"name":"Product Types","description":"Tracked product type categories"},{"name":"Webhooks","description":"Subscribe to regulation change events"},{"name":"Widget","description":"Lightweight compliance checks for embedded widgets"},{"name":"Keys","description":"Free API keys"},{"name":"Predictions","description":"Preview — probabilistic forecasts of state-level regulatory change (not legal advice)"},{"name":"Answer","description":"Deterministic verified question answering"},{"name":"Compliance","description":"Product-level compliance checks, scans, and reformulation"},{"name":"Verified","description":"HempData Verified brand badge lookups"}],"paths":{"/v1/status":{"get":{"operationId":"getStatus","summary":"Health check","description":"Returns API serving status, per-component health, non-serving subsystem detail, version, and current server timestamp. The top-level status reflects the request-serving path only.","tags":["Status"],"security":[],"responses":{"200":{"description":"Service status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"type":"string","enum":["operational","degraded","unhealthy"],"description":"Serving-path status only: 'operational' means API requests are serving normally even if non-serving subsystems (scrapers, freshness pipelines) are degraded — those report under `subsystems`. 'degraded'/'unhealthy' are reserved for the components that affect request serving (database, redis)."},"status_message":{"type":"string","description":"Human explanation — says whether API request serving is affected (only database/redis degradation affects serving); names any degraded non-serving subsystems."},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"components":{"type":"object","description":"Per-component status. Neutral labels; billing = payment processing subsystem.","properties":{"database":{"type":"string"},"redis":{"type":"string"},"billing":{"type":"string"},"scrapers":{"type":"string"},"regulations_freshness":{"type":"string"},"verified_brands_freshness":{"type":"string"},"freshness_watchdog":{"type":"string"}}},"subsystems":{"type":"object","description":"Non-serving subsystem detail. `status` is 'degraded' when any non-serving component (scrapers, freshness pipelines, human review backlog) is impaired; each entry names the component and why.","properties":{"status":{"type":"string","enum":["healthy","degraded"]},"degraded":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"status":{"type":"string"},"message":{"type":"string"}}}}}},"data_freshness":{"type":"object"}},"required":["status","status_message","version","timestamp","components"]},"meta":{"type":["object","null"]},"errors":{"type":"null"}}}}}}}}},"/v1/answer":{"get":{"operationId":"getVerifiedAnswer","summary":"Ask a hemp-law question (Verified Answer Engine)","description":"Deterministic, citation-backed answer from verified regulatory data — the same engine behind hempdata.io/ask. No language model in this path: it cannot invent a regulatory number. Returns status=answered with verification + citations, or an honest status=gap (still HTTP 200) when verified data can't answer.","tags":["Answer"],"parameters":[{"name":"q","in":"query","required":true,"description":"The question, 1-500 chars","schema":{"type":"string","minLength":1,"maxLength":500}},{"name":"state","in":"query","required":false,"description":"Two-letter jurisdiction code

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://artifacts.apis.io/hempdata-io/openapi/_original/hempdata-io-api-openapi.json