> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permitcore.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Changelog
> Versioned release notes for the PermitCore API + docs site.
## 2026-06-04 — PD-7 enrichment promotion shipped
The enrichment fields are now on the live wire.
### New endpoint
* **`GET /v1/permits/by-canonical-uid/{canonical_uid}`** — per-permit
detail endpoint. Returns one fully enriched `PermitResponse` row by
its stable cross-jurisdictional `canonical_uid`. See
[Get a permit by canonical\_uid](/api-reference/permits-by-canonical-uid)
for the encoding requirements + RFC 9457 `400` / `404` shapes.
**Encoding heads-up:** clients MUST `encodeURIComponent` the
`canonical_uid` before placing it in the path. Real values contain
`:`, `|`, spaces, AND `/` (e.g. `1:982522764|Sidewalk Shed`,
`182:BLD23/00099`, `85:2026-066944 PP`). Skipping the encode is the
most common integration mistake.
### Additive fields on `PermitResponse` (both list + detail)
* **`cohort`** — buyer-targeting bucket; one of the 18 canonical
cohorts, or `null` for unsegmented rows. Identical taxonomy to
`target_segment` on `/v1/permits/target`.
* **`dq_flags`** — 12-key boolean object from the WS-PE-DQ-2
bounds-rule registry. **Semantic note (SD-039):** `false` on a flag
means *"the rule has not flagged this value,"* NOT *"the value was
independently verified clean."* NULL silver flag values are coerced
to `false`. See [Data freshness → field-level DQ flags](/concepts/data-freshness#field-level-data-quality-flags) for the full registry.
* **Top-level PLUTO-derived fields** — `units_total`, `year_built`,
`building_class`, `zoning_district`, `lot_area`. Denormalized into
the silver layer; populated where known.
* **`description_llm_enriched`** — LLM-extracted feature object
(`scope_summary`, `unit_count`, `square_footage`,
`tenant_improvement_flag`). Distinct column from
`description_extracted`. **Coverage today:** Austin + Chicago
`commercial_new` permits only (\~17,861 prod rows); broader
cross-metro extraction is on the roadmap.
### Nested `pluto` object — detail-endpoint only
The nested `pluto` object (`{is_placeholder, oob}` — PLUTO parcel-data
presence + per-flag DQ status, NYC only) is **populated on
`/v1/permits/by-canonical-uid/{canonical_uid}` and ALWAYS `null` on
`/v1/permits`** by design. The PLUTO LEFT JOIN required to populate
the DQ-status object would add \~75ms p95 to the list query, which
disqualifies it for the browse path. See the [list-vs-detail
asymmetry note](/api-reference/permits#list-vs-detail-asymmetry-the-nested-pluto-object).
### Docs corrections
* The previous `/v1/permits` example's "Coming with enrichment
promotion" section is removed — the fields are on the wire now.
* The data-freshness page's "DQ flags appear in permit-listing
responses" line flips to present tense.
* **Corrected:** the prior data-freshness DQ flag table listed
illustrative flag names (e.g. `val_zero`, `roof_estimated`,
`addr_unmatched`) that did not match the wire. Replaced with the
canonical 12-key registry from `DqFlags` in `openapi.json`
(`issued_date_*`, `valuation_usd_*`, `units_*`, `geocode_*`).
## 2026-06-04 — `/v1/permits` example regenerated from live OpenAPI
The `GET /v1/permits` response example in the docs is now generated
from the live `PermitResponse` schema at
[api.permitcore.io/openapi.json](https://api.permitcore.io/openapi.json),
adopted as the permanent practice (examples are generated, never
hand-written, so the docs stop drifting from the wire).
Three documentation corrections rode along:
* **`cohort` removed from the example.** The `/v1/permits` endpoint
does not emit a `cohort` field today; the cohort surface is the
aggregate `/v1/jurisdictions/{slug}/cohorts/distribution` endpoint
and the `/v1/permits/target` curated variant. The plain `cohort=`
query parameter on `/v1/permits` arrives with the enrichment
promotion (tracked alongside PD-7; lands within the Q2b window).
* **`dq_flags` removed from the example.** The 12-key DQ flag object
is a pipeline-defined contract surfaced via the upstream recency
artifact; `/v1/permits` emission arrives with the same enrichment
promotion. The data-freshness page's "DQ flags appear in permit-
listing responses" line has been reverted to roadmap phrasing.
* **Nested `pluto` object removed from the example.** Same boat —
documented when emission lands.
The example now documents the wire's **real 45-field richer set** —
including `description_raw`, `current_status`, geocode metadata
(`lat/lng/geocode_confidence/geocode_source`), `architect_name`,
`engineer_name`, `owner_name`, and the
`first_seen_at/last_seen_at/last_changed_at` timestamps.
## 2026-06-04 — Rate-limit reset surfaces now quota-kind-aware
The `X-RateLimit-Reset` response header and the 429 problem+json envelope's
`reset_at` field are now interpreted via the binding `quota_kind`:
* **`daily`** — next UTC midnight (full ceiling restores at once).
* **`monthly`** — earliest moment usage ages out of the trailing 30-day
window (slots restore progressively).
* **unlimited** — `X-RateLimit-Reset` is absent; `reset_at` is absent from
the 429 body.
The `reset_at` field has been added to the 429 envelope field map. The
previous "treat monthly 429s as non-sleepable" caveat is removed: both
kinds support sleep on `retry_after_seconds` / `Retry-After` /
`X-RateLimit-Reset` now. See [Rate limits](/concepts/rate-limits).
## 2026-06-04 — Bucket 2 shipped
The endpoint family announced at v1 launch as "Coming \~3 weeks (Bucket 2)" is live.
### Now live
* **`GET /v1/permits`** — paginated permit-listing endpoint with cohort +
jurisdiction + date filters. Returns per-row data with the field-level
DQ flag object. See [Permits (listing endpoint)](/api-reference/permits).
* **`POST /v1/keys` + `GET /v1/keys` + `DELETE /v1/keys/{prefix}`** —
programmatic API key management. See [API key management](/api-reference/keys).
* **`GET /v1/keys/{prefix}/usage`** — per-key request counters + quota
state. See [API key management](/api-reference/keys#get-v1keysprefixusage-per-key-usage).
* **Tier-aware rate limits.** Per-tier monthly request + export ceilings
enforced server-side. Every quota-gated response carries the
`X-RateLimit-*` header family (see [Rate limits](/concepts/rate-limits#per-response-rate-limit-headers)).
* **OpenAPI 3.1 spec** at `https://api.permitcore.io/openapi.json` —
FastAPI-generated from the deployed code; always current.
* **Pricing: tier model simplified to Free / Pro ($89/mo, $890/yr) / Enterprise.**
See permitcore.io/pricing for
the buy flow.
## 2026-05-24 — `v1` public launch
First public release.
### Live at launch
* **`GET /v1/jurisdictions/{slug}/cohorts/distribution`** — per-jurisdiction
cohort breakdown across the canonical 18 cohorts. Cached 1 hour upstream
(`Cache-Control: max-age=3600`).
* **25 US metros covered** (21 MAPPED + 4 DEPLOY-PENDING).
See [Concepts → Jurisdictions](/concepts/jurisdictions) for the status
meanings + per-status metro lists.
* **18 canonical cohorts** classified per permit via PermitCore's LLM-1
classifier. See [Concepts → Cohorts](/concepts/cohorts).
* **Free in-browser sandbox** at
permitcore.io/sandbox — client-side DuckDB-WASM queries against the
last 10 days of permits across the live metros. No signup required.
* **Self-serve signup + Stripe Checkout.** See
permitcore.io/pricing for
the current tier breakdown.
### Coming later
* **Webhook stream** — real-time permit-filing push delivery is on the
roadmap and not yet available.
* Additional cohort splits (e.g., commercial\_roofing, solar) are on
the roadmap.
* Snowflake + BigQuery share endpoints for higher-volume customers.
* MCP server for AI-agent integration.
### Deprecations
None as of this release.
## How to track changes
* This page is the canonical source.
* Major changes are also surfaced in the in-product `/account` dashboard.
* Breaking changes are versioned (`/v2`); the prior major version
receives security patches but no new features.