---
title: "Query regulations"
method: GET
path: "/v1/regulations"
tags: ["Regulations"]
---

# Query regulations

`GET /v1/regulations`

## Request

- Base URL: `https://api.hempdata.io`
- URL: `https://api.hempdata.io/v1/regulations`
- Auth: HTTP bearer

Search and filter hemp regulations across jurisdictions. Supports filtering by state, substance, product type, legal status, confidence score, and verification date.

**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.

## Query parameters

- `state` string, required
- `substance` string
- `product_type` string
- `legal_status` 'legal' | 'restricted' | 'prohibited' | 'gray_area' | 'pending_change'
- `min_confidence` number
- `verified_after` string, date
- `include_changelog` boolean
- `include_sources` boolean
- `include_bills` boolean
- `page` integer
- `per_page` integer
- `format` 'json' | 'csv'

## Response `200`

Paginated list of regulations

- PaginatedRegulationResponse
  - `success` boolean, required
  - `data` Regulation[], required
    - `id` string, uuid, nullable, required: Unique regulation record identifier Null on a canon row (source: "canon").
    - `jurisdiction` string, required: Two-letter state code or DC
    - `substance` string, required: Regulated substance name
    - `product_type` string, required: Product type category
    - `legal_status` 'legal' | 'restricted' | 'prohibited' | 'gray_area' | 'pending_change', required: Current legal status in this jurisdiction
    - `federal_status` string: Federal legal status for this substance/product combination
    - `thc_limit_pct_dryweight` number, nullable: Maximum THC concentration as percentage of dry weight
    - `thc_limit_mg_per_serving` number, nullable: Maximum THC in milligrams per serving
    - `thc_limit_mg_per_container` number, nullable: Maximum THC in milligrams per container/package
    - `thc_measurement_method` string, nullable: Required method for measuring THC content (e.g. post-decarboxylation, total THC)
    - `cbd_limit_mg_per_serving` number, nullable: Maximum CBD in milligrams per serving, if regulated
    - `age_restriction` integer, nullable: Minimum age for purchase
    - `age_verification_method` string, nullable: Required age verification method (e.g. id_scan, self_attestation)
    - `labeling_required` boolean, nullable: Whether specific labeling is mandated
    - `warning_text_verbatim` string, nullable: Exact warning text required on packaging, if any
    - `testing_standard` string, nullable: Required testing standard or accreditation (e.g. ISO 17025)
    - `testing_panels_required` string[], nullable: List of required testing panels (e.g. potency, pesticides, heavy_metals, microbials)
    - `shipping_status` string, nullable: Whether the product can be shipped to/from this state
    - `carrier_restrictions` string[], nullable: Carriers that restrict or prohibit shipping this product
    - `license_required` boolean, nullable: Whether a state license is required to sell
    - `license_type` string, nullable: Type of license required (e.g. hemp_processor, retail_cannabis)
    - `enforcement_date` string, date, nullable: Date the regulation took or takes effect
    - `enforcement_agency` string, nullable: Government agency responsible for enforcement
    - `penalty_range` string, nullable: Summary of penalties for non-compliance
    - `source_urls` string[], nullable: URLs to official source documents
    - `source_documents` string[], nullable: Names or references of source documents
    - `plain_english` string, nullable: Human-readable summary of the regulation
    - `block_sale` boolean, nullable: Whether sales should be blocked in this jurisdiction (compliance recommendation)
    - `effective_date` string, date, nullable: Date the regulation became effective
    - `expiry_date` string, date, nullable: Date the regulation expires or sunsets, if applicable
    - `related_bills` object[], nullable: Related legislative bills
      - `bill_id` string
      - `title` string
      - `status` string
      - `url` string, uri
    - `last_verified` string, date-time, required: When this regulation was last verified by a human analyst
    - `verification_tier` 'attorney_reviewed' | 'analyst_verified' | 'automated' | 'unverified', required: Level of human verification applied
    - `confidence_score` number, required: Confidence score from 0 to 1 indicating data reliability
    - `legal_status_source` 'canon_overlay' | 'db': 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` 'canon': 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` 'canon': 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` string, nullable: The verified fact id behind a canon verdict / canon prose.
    - `canon_verdict` string: The verdict line /v1/answer prints for this state + substance (canon rows only).
    - `canon_scope` 'substance_level': Canon rows answer for the substance; product-form rules are in state_rule, not evaluated.
    - `state_rule` string, nullable: The state's verified fact (canonical phrasing), verbatim.
    - `canon_form_note` string: 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` 'canon' | 'fallback_map' | 'unsettled': 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).
  - `meta` PaginationMeta, required
    - `page` integer, required
    - `per_page` integer, required
    - `total` integer, required
    - `total_pages` integer, required
  - `errors` ApiError[], nullable
    - `code` string, required: Machine-readable error code
    - `message` string, required: Human-readable error message
    - `field` string, nullable: Field that caused the error, if applicable

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/hempdata/apis/hempdata-api.md) · [All operations](https://skmtc.dev/hempdata/apis/hempdata-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hempdata/apis/hempdata-api/revisions/2c2946badd40?raw)