Skip to main content

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

​
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, 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.

​
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).
  • POST /v1/keys + GET /v1/keys + DELETE /v1/keys/{prefix} — programmatic API key management. See API key management.
  • GET /v1/keys/{prefix}/usage — per-key request counters + quota state. See API key management.
  • 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).
  • 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,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 for the status meanings + per-status metro lists.
  • 18 canonical cohorts classified per permit via PermitCore’s LLM-1 classifier. See 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.