{"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://hempdataapi.com","email":"support@hempdataapi.com"}},"servers":[{"url":"https://api.hempdataapi.com","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/status":{"get":{"operationId":"getStatus","summary":"Health check","description":"Returns API health status, version, and current server timestamp.","tags":["Status"],"security":[],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy"],"example":"healthy"},"version":{"type":"string","example":"1.0.0"},"timestamp":{"type":"string","format":"date-time","example":"2026-03-18T12:00:00Z"}},"required":["status","version","timestamp"]}}}}}}},"/v1/regulations":{"get":{"operationId":"queryRegulations","summary":"Query regulations","description":"Search and filter hemp regulations across jurisdictions. Supports filtering by state, substance, product type, legal status, confidence score, and verification date.\n\n**Tier-gated response fields:** the set of columns returned depends on the subscriber's tier. Free returns the core record (id, jurisdiction, substance, product_type, legal_status, federal_status, thc_limits, verification metadata). Retailer adds shipping/age/license fields. Brand adds labeling, testing, enforcement, penalty, and plain_english fields. Enterprise additionally returns changelog, source_urls, source_documents, and related_bills. Lower tiers may still pass `include_changelog/include_sources/include_bills=true` — the params are silently ignored and `meta.upgrade_hint` surfaces the required tier.","tags":["Regulations"],"parameters":[{"name":"state","in":"query","required":true,"description":"Comma-separated list of two-letter state codes (e.g. CO,CA,NY)","schema":{"type":"string"},"example":"CO,CA"},{"name":"substance","in":"query","required":false,"description":"Filter by substance (e.g. delta-9-thc, cbd, delta-8-thc)","schema":{"type":"string"}},{"name":"product_type","in":"query","required":false,"description":"Filter by product type (e.g. edibles, topicals, flower, tinctures)","schema":{"type":"string"}},{"name":"legal_status","in":"query","required":false,"description":"Filter by legal status","schema":{"type":"string","enum":["legal","restricted","prohibited","gray_area","pending_change"]}},{"name":"min_confidence","in":"query","required":false,"description":"Minimum confidence score (0 to 1)","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"verified_after","in":"query","required":false,"description":"Only return regulations verified after this ISO 8601 date","schema":{"type":"string","format":"date"}},{"name":"include_changelog","in":"query","required":false,"description":"Include change history for each regulation","schema":{"type":"boolean","default":false}},{"name":"include_sources","in":"query","required":false,"description":"Include source URLs and documents","schema":{"type":"boolean","default":false}},{"name":"include_bills","in":"query","required":false,"description":"Include related legislative bills","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"format","in":"query","required":false,"description":"Response format","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Paginated list of regulations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedRegulationResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/regulations/{id}":{"get":{"operationId":"getRegulationById","summary":"Get single regulation","description":"Retrieve a single regulation record by its UUID.","tags":["Regulations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Regulation UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Single regulation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Regulation"}}}},"404":{"description":"Regulation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/regulations/changelog":{"get":{"operationId":"getRegulationChangelog","summary":"Regulation change history","description":"Returns a chronological log of regulation changes, useful for tracking legislative updates over time.\n\n**Tier gating:** this endpoint requires Enterprise tier. Free/Retailer/Brand callers receive a 402 with code `UPGRADE_REQUIRED`.","tags":["Regulations"],"parameters":[{"name":"state","in":"query","required":false,"description":"Filter by two-letter state code","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated changelog entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedChangelogResponse"}}}},"402":{"description":"Upgrade required — Enterprise tier only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/regulations/compare":{"get":{"operationId":"compareRegulations","summary":"Compare state regulations","description":"Side-by-side comparison of regulations across two or more states. Useful for multi-state compliance planning.","tags":["Regulations"],"parameters":[{"name":"states","in":"query","required":true,"description":"Comma-separated list of state codes (minimum 2)","schema":{"type":"string"},"example":"CO,CA,NY"},{"name":"substance","in":"query","required":false,"description":"Filter comparison to a specific substance","schema":{"type":"string"}},{"name":"product_type","in":"query","required":false,"description":"Filter comparison to a specific product type","schema":{"type":"string"}}],"responses":{"200":{"description":"Comparison results grouped by state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Comparison"}}}},"400":{"description":"Fewer than 2 states provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/states":{"get":{"operationId":"listStates","summary":"List all states","description":"Returns all 50 US states plus DC with summary regulatory information.","tags":["States"],"responses":{"200":{"description":"List of state summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_StateList"}}}}}}},"/v1/states/{code}":{"get":{"operationId":"getStateByCode","summary":"Get state profile","description":"Detailed regulatory profile for a single state.","tags":["States"],"parameters":[{"name":"code","in":"path","required":true,"description":"Two-letter state code (e.g. CO, CA, NY)","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"State profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_StateProfile"}}}},"404":{"description":"State not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/substances":{"get":{"operationId":"listSubstances","summary":"List substances","description":"Returns all tracked hemp-derived substances (e.g. delta-9-thc, cbd, delta-8-thc, cbg, cbn).","tags":["Substances"],"responses":{"200":{"description":"List of substances","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_SubstanceList"}}}}}}},"/v1/product-types":{"get":{"operationId":"listProductTypes","summary":"List product types","description":"Returns all tracked product types (e.g. edibles, topicals, flower, tinctures, beverages, vapes).","tags":["Product Types"],"responses":{"200":{"description":"List of product types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_ProductTypeList"}}}}}}},"/v1/webhooks":{"post":{"operationId":"createWebhook","summary":"Create webhook","description":"Subscribe to regulation change events via webhook. Requires an HTTPS endpoint URL.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateRequest"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Webhook"}}}},"400":{"description":"Invalid request (e.g. non-HTTPS URL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"List all webhook subscriptions for the authenticated account.","tags":["Webhooks"],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_WebhookList"}}}}}}},"/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete webhook","description":"Remove a webhook subscription.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"type":"string","example":"Webhook deleted successfully"}}}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/widget/check":{"post":{"operationId":"widgetComplianceCheck","summary":"Widget compliance check","description":"Lightweight compliance check designed for embeddable widgets. Determines whether a product can be sold in a given state. Accepts either a state code or an IP address for geo-lookup.","tags":["Widget"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetCheckRequest"}}}},"responses":{"200":{"description":"Compliance check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_WidgetCheck"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/billing/checkout":{"post":{"operationId":"createCheckoutSession","summary":"Create checkout session","description":"Generates a Stripe checkout session URL for subscribing to a plan.","tags":["Billing"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri","example":"https://checkout.stripe.com/c/pay/cs_live_..."},"session_id":{"type":"string","example":"cs_live_..."}}}}}}}}}}},"/v1/billing/portal":{"post":{"operationId":"createBillingPortalSession","summary":"Create billing portal session","description":"Generates a Stripe billing portal URL for managing an existing subscription.","tags":["Billing"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRequest"}}}},"responses":{"200":{"description":"Portal session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"portal_url":{"type":"string","format":"uri","example":"https://billing.stripe.com/p/session/..."}}}}}}}}}}},"/v1/predictions/{state}":{"get":{"operationId":"getStatePrediction","summary":"(Preview) Forecast regulatory change for a state","description":"Aggregates public bill tracking, pending regulations, and named federal enforcement dates into a probabilistic change signal. **Preview endpoint — not legal advice.** Output must not be relied on for stocking, shipping, or formulation decisions without counsel review. Responses are re-stamped with the current disclaimer, even on cache hits. The endpoint is gated behind the standard authenticated + rate-limited `/v1/*` pipeline.","tags":["Predictions"],"parameters":[{"name":"state","in":"path","required":true,"description":"Two-letter state code (e.g. CO, CA, NY).","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"horizon_days","in":"query","required":false,"description":"Forecast horizon window in days (default 90, min 7, max 730).","schema":{"type":"integer","minimum":7,"maximum":730,"default":90}},{"name":"refresh","in":"query","required":false,"description":"If true, bypass the 24h cache and recompute from live signals.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Prediction result (Preview). Always includes the current disclaimer.","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["state","horizon_days","change_probability","confidence","risk_level","predicted_changes","signal_counts","methodology_notes","calculated_at","disclaimer"],"properties":{"state":{"type":"string","example":"CO"},"horizon_days":{"type":"integer","example":90},"change_probability":{"type":"number","format":"float","minimum":0,"maximum":0.97},"confidence":{"type":"number","format":"float","minimum":0.35,"maximum":0.9},"risk_level":{"type":"string","enum":["low","moderate","high","critical"]},"predicted_changes":{"type":"array","items":{"type":"object","properties":{"substance":{"type":"string"},"direction":{"type":"string","enum":["tighter","looser","unclear"]},"estimated_effective_date":{"type":"string","nullable":true,"format":"date"},"likely_triggers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bill","federal_enforcement","regulation_sunset"]},"reference_id":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number","format":"float"}}}},"reasoning":{"type":"string"}}}},"signal_counts":{"type":"object","properties":{"active_bills":{"type":"integer"},"pending_regulations":{"type":"integer"},"federal_triggers":{"type":"integer"}}},"methodology_notes":{"type":"string"},"calculated_at":{"type":"string","format":"date-time"},"disclaimer":{"type":"string","description":"Re-stamped on every response. Required."}}},"meta":{"type":"object","properties":{"cached":{"type":"boolean"},"calculated_at":{"type":"string","format":"date-time"},"legal_notice":{"type":"string"}}}}}}}},"400":{"description":"Validation error (bad state code or horizon).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Predictions table unavailable (e.g. migration not applied).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"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","format":"uuid","description":"Unique regulation record identifier"},"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}},"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"}},"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"}},"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"]},"CheckoutRequest":{"type":"object","properties":{"tier":{"type":"string","enum":["starter","professional","enterprise"],"description":"Subscription tier"},"billing_period":{"type":"string","enum":["monthly","annual"],"description":"Billing frequency"},"email":{"type":"string","format":"email","description":"Customer email address"},"success_url":{"type":"string","format":"uri","description":"URL to redirect to after successful payment"},"cancel_url":{"type":"string","format":"uri","description":"URL to redirect to if payment is cancelled"}},"required":["tier","billing_period","email","success_url","cancel_url"]},"PortalRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email associated with the subscription"},"return_url":{"type":"string","format":"uri","description":"URL to redirect to when leaving the portal"}},"required":["email","return_url"]},"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"]}}},"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":"Billing","description":"Subscription management via Stripe"},{"name":"Predictions","description":"Preview — probabilistic forecasts of state-level regulatory change (not legal advice)"}]}