{"openapi":"3.1.0","info":{"title":"DevCannabis API","description":"Versioned, stable read API over DevCannabis's normalized multi-state\ncannabis data. Every number traces to a named government regulator via citations.\n\n**Access**: all routes here are keyless and free for fair, non-commercial use, behind a\nper-IP rate limit. Per-operator granularity, bulk export, and commercial/resale or\nmodel-training use are governed by the access policy (https://devcannabis.com/access-policy)\n— bulk and commercial reuse require an approved API key or written permission.\n\n**Reading the data honestly**: jurisdictions report on their own cadence (MA daily,\nCO/OR/MI monthly, WA annual fiscal years, FL weekly medical volumes) — responses carry\n`cadence`, `data_through`, and `period_label` so you never mistake an annual number for\na monthly one. Suppressed values are returned as data, never dropped. Check each\nmetric's `value_kind` before summing: flows sum, stocks and prices never do.","version":"1.0.0"},"paths":{"/":{"get":{"summary":"V1 Index","description":"Service index: where everything lives. The starting point for a new consumer.","operationId":"v1_index__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/states":{"get":{"summary":"V1 States","description":"Live and planned jurisdictions. `live` states have dashboards and data;\n`planned` states are on the roadmap seeking a lead.","operationId":"v1_states_states_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/states/{state}/summary":{"get":{"summary":"V1 State Summary","description":"Headline market figures, anchored to the source's latest reported period.","operationId":"v1_state_summary_states__state__summary_get","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string","title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/states/{state}/timeseries":{"get":{"summary":"V1 State Timeseries","description":"Per-channel timeseries of one flow metric, rolled up from the jurisdiction's\nnative grain (requests finer than the source are clamped, never interpolated).","operationId":"v1_state_timeseries_states__state__timeseries_get","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string","title":"State"}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","description":"Flow metric: sales, units_sold, transactions","default":"sales","title":"Metric"},"description":"Flow metric: sales, units_sold, transactions"},{"name":"rollup","in":"query","required":false,"schema":{"type":"string","description":"daily | weekly | monthly (clamped to the source's grain)","default":"weekly","title":"Rollup"},"description":"daily | weekly | monthly (clamped to the source's grain)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/states/{state}/categories":{"get":{"summary":"V1 State Categories","description":"Product-category sales share over a trailing window. Only jurisdictions that\npublish category splits (MA today) return multiple categories.","operationId":"v1_state_categories_states__state__categories_get","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string","title":"State"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":730,"minimum":7,"description":"Trailing window ending at data_through","default":90,"title":"Days"},"description":"Trailing window ending at data_through"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/states/{state}/price":{"get":{"summary":"V1 State Price","description":"Official price series in native units (never aggregated further).","operationId":"v1_state_price_states__state__price_get","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string","title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/states/{state}/config":{"get":{"summary":"V1 State Config","description":"The jurisdiction's capability/module/methodology configuration.","operationId":"v1_state_config_states__state__config_get","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string","title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/market/cross-state":{"get":{"summary":"Market Cross State","description":"All-time statewide sales by jurisdiction, for cross-market comparison.\n\nMirrors ``landing_stats._sales_tracked`` exactly (sum of the latest\nstate-level ``sales`` across all channels) but grouped by jurisdiction,\nso the comparison bars reconcile with the landing-page headline total.\nJurisdictions with no dollar sales (e.g. Florida, medical-only) are not\ncomparable on this metric, so they are listed under ``omitted`` with a\nreason instead of being silently absent — a consumer summing ``states``\nmust not read the total as \"all live states\".","operationId":"market_cross_state_market_cross_state_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/citations":{"get":{"summary":"Get Citations","description":"Return canonical citations with optional target/source filters.","operationId":"get_citations_citations_get","parameters":[{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"metric/chart/operator/event/lineage/location/legal_case/methodology/pdf/source_profile","title":"Target Type"},"description":"metric/chart/operator/event/lineage/location/legal_case/methodology/pdf/source_profile"},{"name":"target_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Target record/key, e.g. event_key or PDF filename","title":"Target Id"},"description":"Target record/key, e.g. event_key or PDF filename"},{"name":"metric","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Metric key linked to the citation","title":"Metric"},"description":"Metric key linked to the citation"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Jurisdiction/state code, e.g. FL","title":"State"},"description":"Jurisdiction/state code, e.g. FL"},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Source type, e.g. government_report or market_event","title":"Source Type"},"description":"Source type, e.g. government_report or market_event"},{"name":"confidence","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"source_confirmed/parser_validated/needs_review/inferred/rejected","title":"Confidence"},"description":"source_confirmed/parser_validated/needs_review/inferred/rejected"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/events":{"get":{"summary":"Get Events","description":"Return global + scoped market events for chart overlays.","operationId":"get_events_events_get","parameters":[{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"State code (e.g., FL)","title":"State"},"description":"State code (e.g., FL)"},{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Jurisdiction code/name; defaults to state when omitted","title":"Jurisdiction"},"description":"Jurisdiction code/name; defaults to state when omitted"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country code for country-scoped events","default":"US","title":"Country"},"description":"Country code for country-scoped events"},{"name":"metric","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Metric key requesting overlays","title":"Metric"},"description":"Metric key requesting overlays"},{"name":"chart","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chart key/domain requesting overlays","title":"Chart"},"description":"Chart key/domain requesting overlays"},{"name":"chart_domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Canonical chart domain requesting overlays","title":"Chart Domain"},"description":"Canonical chart domain requesting overlays"},{"name":"operator","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Operator/canonical entity name","title":"Operator"},"description":"Operator/canonical entity name"},{"name":"scope_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter to a specific event scope type","title":"Scope Type"},"description":"Filter to a specific event scope type"},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter to a specific event type","title":"Event Type"},"description":"Filter to a specific event type"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Earliest event date","title":"Start Date"},"description":"Earliest event date"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Latest event date","title":"End Date"},"description":"Latest event date"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketEventListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sources":{"get":{"summary":"List Official Sources","description":"List canonical official public government/regulatory sources.","operationId":"list_official_sources_sources_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/observations":{"get":{"summary":"List Observations","description":"Normalized metric observations, verbatim per the published schema.\n\nSuppressed rows are returned (``value: null``, ``suppressed: true``), never dropped —\nsuppression is data. Restated history is reachable via ``include_restated=true`` and\neach row's ``restates_observation_id``.","operationId":"list_observations_observations_get","parameters":[{"name":"jurisdiction_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Jurisdiction code (e.g. WA). Omit for all.","title":"Jurisdiction Code"},"description":"Jurisdiction code (e.g. WA). Omit for all."},{"name":"metric","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Metric code (open vocabulary, e.g. sales, patient_count)","title":"Metric"},"description":"Metric code (open vocabulary, e.g. sales, patient_count)"},{"name":"cadence","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"daily | weekly | monthly | quarterly | annual","title":"Cadence"},"description":"daily | weekly | monthly | quarterly | annual"},{"name":"geo_level","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"state | county | province | municipality","title":"Geo Level"},"description":"state | county | province | municipality"},{"name":"market_segment","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"medical | adult_use | combined | delivery | wholesale | unknown","title":"Market Segment"},"description":"medical | adult_use | combined | delivery | wholesale | unknown"},{"name":"buyer_residency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"resident | non_resident | all","title":"Buyer Residency"},"description":"resident | non_resident | all"},{"name":"product_category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Canonical category (e.g. flower, vape, all)","title":"Product Category"},"description":"Canonical category (e.g. flower, vape, all)"},{"name":"is_aggregate","in":"query","required":false,"schema":{"type":"boolean","description":"Aggregate rows are public; per-operator rows require auth","default":true,"title":"Is Aggregate"},"description":"Aggregate rows are public; per-operator rows require auth"},{"name":"period_start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Rows with period_start on/after this date","title":"Period Start"},"description":"Rows with period_start on/after this date"},{"name":"period_end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Rows with period_end on/before this date","title":"Period End"},"description":"Rows with period_end on/before this date"},{"name":"include_restated","in":"query","required":false,"schema":{"type":"boolean","description":"Include superseded rows (default: is_latest only)","default":false,"title":"Include Restated"},"description":"Include superseded rows (default: is_latest only)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Keyset cursor: last id from the previous page","default":0,"title":"Cursor"},"description":"Keyset cursor: last id from the previous page"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CitationLinkResponse":{"properties":{"id":{"type":"integer","title":"Id"},"citation_id":{"type":"integer","title":"Citation Id"},"target_type":{"type":"string","title":"Target Type"},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id"},"metric_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metric Key"},"field_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Name"},"claim_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Claim Date"},"support_level":{"type":"string","title":"Support Level"},"quote_or_excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Or Excerpt"},"page_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Number"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","citation_id","target_type","support_level"],"title":"CitationLinkResponse","description":"Public citation-target link."},"CitationListResponse":{"properties":{"citations":{"items":{"$ref":"#/components/schemas/CitationResponse"},"type":"array","title":"Citations"},"count":{"type":"integer","title":"Count"},"citation_policy":{"type":"string","title":"Citation Policy","default":"Citations are canonical source records. CitationLink rows attach them to metrics, charts, events, lineage, locations, legal claims, PDFs, source profiles, and methodology notes without duplicating source fields."}},"type":"object","required":["citations","count"],"title":"CitationListResponse","description":"Filtered citation collection response."},"CitationResponse":{"properties":{"id":{"type":"integer","title":"Id"},"source_type":{"type":"string","title":"Source Type"},"title":{"type":"string","title":"Title"},"publisher":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher"},"publisher_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Type"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"archive_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archive Url"},"document_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Document Date"},"retrieved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Retrieved At"},"last_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Verified At"},"confidence":{"type":"string","title":"Confidence"},"citation_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Text"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"links":{"items":{"$ref":"#/components/schemas/CitationLinkResponse"},"type":"array","title":"Links"}},"type":"object","required":["id","source_type","title","confidence"],"title":"CitationResponse","description":"Public canonical citation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MarketEventListResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/MarketEventResponse"},"type":"array","title":"Events"},"count":{"type":"integer","title":"Count"},"verification_policy":{"type":"string","title":"Verification Policy","default":"source_confirmed events link to a public source; inferred/needs_review events are contextual markers, not authoritative claims."}},"type":"object","required":["events","count"],"title":"MarketEventListResponse","description":"Market event list response with policy copy for UI consumers."},"MarketEventResponse":{"properties":{"id":{"type":"integer","title":"Id"},"event_key":{"type":"string","title":"Event Key"},"title":{"type":"string","title":"Title"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"event_date":{"type":"string","format":"date","title":"Event Date"},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date"},"scope_type":{"type":"string","title":"Scope Type"},"scope_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope Value"},"event_type":{"type":"string","title":"Event Type"},"impact_level":{"type":"string","title":"Impact Level"},"applies_to_metrics":{"items":{"type":"string"},"type":"array","title":"Applies To Metrics"},"chart_domains":{"items":{"type":"string"},"type":"array","title":"Chart Domains"},"display_mode":{"type":"string","title":"Display Mode","default":"line"},"display_anchor":{"type":"string","title":"Display Anchor","default":"start"},"default_visible":{"type":"boolean","title":"Default Visible","default":true},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Label"},"verification_status":{"type":"string","title":"Verification Status"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","event_key","title","event_date","scope_type","event_type","impact_level","verification_status"],"title":"MarketEventResponse","description":"Public market event overlay record."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"servers":[{"url":"/api/v1"}]}