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

# Permits (listing endpoint)

> Paginate permit rows by jurisdiction × date with the full normalized + source + enrichment fields.

Returns paginated permit rows filtered by jurisdiction + date range.
The response example below is **generated from the live OpenAPI spec**
at [api.permitcore.io/openapi.json](https://api.permitcore.io/openapi.json) —
re-pulled before each docs deploy, never hand-written.

## Authentication

`Authorization: Bearer <your-api-key>` — see [Authentication](https://docs.permitcore.io/authentication.md).

## Query parameters

These are the parameters `/v1/permits` actually accepts, per the live
OpenAPI spec. There is **no `cohort` parameter on `/v1/permits`** — buyer-segment
filtering lives on the [`/v1/permits/target`](#the-v1permitstarget-variant)
variant via `target_segment`.

| Param | Type | Notes |
| - | - | - |
| `jurisdiction` | string (slug) | Comma-separated jurisdiction slug(s), e.g. `nyc`, `la`. |
| `issued_after` | ISO 8601 date | Lower bound for `issued_date` (YYYY-MM-DD). |
| `issued_before` | ISO 8601 date | Upper bound for `issued_date`. |
| `permit_type` | string | Filter by normalized permit type. |
| `work_class` | string | Filter by work class. |
| `bbox` | string | `minLon,minLat,maxLon,maxLat` bounding box. |
| `min_valuation` | integer | Minimum `valuation_usd`. |
| `has_extracted` | boolean | Only rows with LLM-extracted enrichment. |
| `updated_since` | ISO 8601 date-time | Rows changed since a timestamp (delta sync). |
| `contractor_canonical_id` | integer | Filter to one canonical contractor. |
| `parcel_key` | string | Filter to one parcel. |
| `q` | string | Free-text search (contractor / owner). Min 3 chars. |
| `order_by` | enum | `issued_date` (default) · `applied_date` · `last_seen_at` · `valuation_usd`. |
| `order_dir` | enum | `asc` · `desc`. |
| `page` | integer | 1-indexed page number (offset pagination). |
| `per_page` | integer | Page size; 1–500. |
| `cursor` | string | Opaque keyset cursor for deep paging — see [Pagination](#pagination). When supplied, `page` is ignored. |

## Response shape

The example below is generated from the `PermitResponse` schema in
`openapi.json`. The enrichment fields (`cohort`, `dq_flags`, top-level
PLUTO-derived fields, `description_llm_enriched`) are now on the wire as
of the 2026-06-04 promotion. The nested `pluto` DQ-status object is
**list-endpoint NULL by design** — see the list-vs-detail asymmetry note below.

```json theme={null}
{
  "items": [
    {
      "id": 4218034,
      "jurisdiction_slug": "nyc",
      "source_permit_id": "BT-202601090",
      "canonical_uid": "1:BT-202601090",
      "filing_id": null,

      "address_full": "82 ASP 1ST FLOOR, Manhattan, NY 10009",
      "address_street": "82 ASP",
      "address_city": "Manhattan",
      "address_state": "NY",
      "address_zip": "10009",
      "parcel_apn": "1004920019",
      "lat": 40.7271,
      "lng": -73.9836,
      "geocode_confidence": 0.92,
      "geocode_source": "city_geocoder_v2",

      "permit_type_raw": "BUILDING/EW",
      "permit_type_normalized": "alteration",
      "work_class": "alteration_minor",
      "building_subtype": "tenant_improvement",
      "is_new_construction": false,
      "is_alteration": true,
      "is_demolition": false,

      "units_residential": null,
      "units_commercial": null,
      "units_total": null,
      "square_footage_total": null,
      "valuation_usd": 18400,

      "year_built": 1925,
      "building_class": "O4",
      "zoning_district": "C6-2",
      "lot_area": 2540,

      "applied_date": "2026-05-20",
      "issued_date": "2026-05-27",
      "finaled_date": null,
      "expired_date": null,

      "current_status": "issued",
      "status_raw": "ISSUED-PARTIAL",
      "description_raw": "Interior reno @ unit 3R; partition + finishes; no MEP scope",
      "description_extracted": null,
      "description_llm_enriched": null,

      "applicant_name": null,
      "applicant_role": null,
      "contractor_name": "MIDTOWN BUILD CO INC",
      "contractor_license": "GC-0148921",
      "architect_name": null,
      "engineer_name": null,
      "owner_name": null,

      "source_url": "https://www.nyc.gov/site/buildings/permit/BT-202601090",
      "first_seen_at": "2026-05-27T03:14:22Z",
      "last_seen_at": "2026-06-04T03:11:08Z",
      "last_changed_at": "2026-05-27T03:14:22Z",

      "cohort": "commercial_alteration",
      "dq_flags": {
        "issued_date_is_parse_bug": false,
        "issued_date_is_placeholder": false,
        "issued_date_is_future_dated": false,
        "valuation_usd_is_placeholder": false,
        "valuation_usd_is_oob": false,
        "units_residential_is_placeholder": false,
        "units_total_is_placeholder": false,
        "units_residential_is_oob": false,
        "units_total_is_oob": false,
        "units_commercial_is_placeholder": false,
        "geocode_is_sentinel": false,
        "geocode_is_oob": false
      },
      "pluto": null
    }
  ],
  "pagination": {
    "total_count": 1000,
    "next_page": 2,
    "has_more": true
  }
}
```

The `pagination` object above is abbreviated for readability. See
[Pagination](#pagination) for the full, canonical envelope both this endpoint
and `/v1/permits/target` return.

### Pagination

`/v1/permits` and `/v1/permits/target` return the **same** response envelope:

```json theme={null}
{
  "items": [ /* … */ ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 40,
    "total_count": 1000,
    "total_count_is_estimate": true,
    "has_more": true,
    "next_page": 2,
    "prev_page": null,
    "next_cursor": "eyJpc3N1ZWRfZGF0ZSI6…"
  },
  "filters_applied": { "jurisdiction": "nyc" },
  "query_time_ms": 34
}
```

* **`total_count`** is capped at 1,000 on selective-filter queries, and
  jurisdiction-only queries use a fast row estimate. When
  `total_count_is_estimate` or `has_more` is `true`, the true total exceeds
  `total_count` — render it as `"1,000+"` if you surface it directly.
* **Offset paging** (both endpoints): pass `page` + `per_page`.
* **Keyset / cursor paging** (`/v1/permits` only): pass the prior response's
  `pagination.next_cursor` back as the `cursor` query parameter to page deep or
  across jurisdictions without an `OFFSET` scan. When `cursor` is supplied,
  `page` is ignored; the cursor is bound to the request's `order_by`/`order_dir`,
  so keep those stable while paging. `next_cursor` is `null` on the last page.
  `/v1/permits/target` is **offset-only** (`page`/`per_page`).

### What's on the wire

The list-endpoint shape carries **58 fields** organized as:

* **Identity** — `id`, `jurisdiction_slug`, `source_permit_id`, `canonical_uid`, `filing_id`
* **Address** — `address_full`, `address_street`, `address_city`, `address_state`, `address_zip`, `parcel_apn`
* **Geocode metadata** — `lat`, `lng`, `geocode_confidence`, `geocode_source`
* **Type + classification** — `permit_type_raw`, `permit_type_normalized`, `work_class`, `building_subtype`, `is_new_construction`, `is_alteration`, `is_demolition`
* **Scope** — `units_residential`, `units_commercial`, `units_total`, `square_footage_total`, `valuation_usd`
* **PLUTO-derived (denormalized)** — `year_built`, `building_class`, `zoning_district`, `lot_area`
* **Dates** — `applied_date`, `issued_date`, `finaled_date`, `expired_date`
* **Status + description** — `current_status`, `status_raw`, `description_raw`, `description_extracted`, `description_llm_enriched`
* **People** — `applicant_name`, `applicant_role`, `contractor_name`, `contractor_license`, `architect_name`, `engineer_name`, `owner_name`
* **Source link + timestamps** — `source_url`, `first_seen_at`, `last_seen_at`, `last_changed_at`
* **Enrichment** — `cohort`, `dq_flags`, `pluto`

Most fields are **nullable** — coverage varies by jurisdiction and by upstream record completeness.

### Enrichment field semantics

* **`cohort`** — the buyer-targeting bucket the row classifies into, one of the 23 canonical segments. `null` = row not in the cohort matview OR in the matview but unsegmented. Identical taxonomy to `target_segment` on `/v1/permits/target`. See [Concepts → Cohorts](https://docs.permitcore.io/concepts/cohorts.md).
* **`dq_flags`** — 12-key boolean object from the bounds-rule registry. All 12 keys are always present when this field is non-null. **Semantic note:** `false` means *"the rule has not flagged this value,"* NOT *"the value was independently verified clean."* NULL silver flag values are coerced to `false` per the SD-039 rule. See [Data freshness → field-level DQ flags](https://docs.permitcore.io/concepts/data-freshness.md#field-level-data-quality-flags) for the full flag set + semantics.
* **`description_llm_enriched`** — LLM-extracted feature object (e.g. `scope_summary`, `unit_count`, `square_footage`, `tenant_improvement_flag`). Distinct column from `description_extracted` (which is adapter-populated, per-jurisdiction shape). **Coverage today:** Austin + Chicago `commercial_new` permits only (\~17,861 prod rows). Broader cross-metro LLM extraction is on the roadmap.

### List-vs-detail asymmetry: the nested `pluto` object

The nested `pluto` object (PLUTO parcel-data presence + per-flag DQ
status — `{is_placeholder, oob}`) is **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. To get the populated `pluto` object, query the per-permit detail
endpoint:

```
GET /v1/permits/by-canonical-uid/{canonical_uid}
```

See [Get a permit by canonical\_uid](https://docs.permitcore.io/api-reference/permits-by-canonical-uid.md).

Note that the **top-level PLUTO-derived fields** (`year_built`,
`building_class`, `zoning_district`, `lot_area`, `units_total`) are
denormalized into the silver layer and DO populate on this endpoint
when known. Only the nested `pluto` *DQ-status* object is detail-only.

## The `/v1/permits/target` variant

`/v1/permits/target` returns the same response envelope but exposes a curated
commercial/multifamily/ADU slice, filtered by `target_segment=<segment>`. This is
the cohort-classified slice that the site's recency surfaces query. It also adds
geo filters (`state`, `metro_cbsa`), value bounds (`value_min`/`value_max`), and
enrichment filters (`climate_zone`, `roof_area_min`, `hvac_tonnage_min`). It is
**offset-only** (no `cursor`).

`target_segment` accepts a comma-separated list of the **23 canonical segment
slugs** (see [Cohorts](https://docs.permitcore.io/concepts/cohorts.md)). Behavior:

* **Valid segment with zero rows in window:** `200 OK` with an empty
  `items` array — no `404`. Use `pagination.total_count` to confirm
  the empty result.
* **Invalid slug** (not in the 23-segment enum): `422 Unprocessable Entity`
  ([`invalid-target-segment`](https://docs.permitcore.io/errors/invalid-target-segment)) with a
  problem+json body enumerating the accepted whitelist.
* **Newer cohort caveat:** `multifamily_mep` is filterable and populated but
  **not yet certified to the ≥99% precision bar** of the other 22 segments —
  currently 3 metros (primarily Austin), largely historical. See the note on
  [Cohorts](https://docs.permitcore.io/concepts/cohorts.md). The other 22 are the established, certified set.

> [!NOTE]
>
> `/v1/permits/target` also has a separate `cohort` parameter — but it is a
> **per-manufacturer cohort** (an A5 YAML basename such as `roofing-manufacturer`),
> **not** a buyer segment. An unknown value returns `400`
> ([`unknown-cohort`](https://docs.permitcore.io/errors/unknown-cohort)). Use `target_segment` for segment
> filtering; use `cohort` only for manufacturer-cohort targeting.

## Quotas

Quotas are tier-based and apply to every request against this endpoint.
See [Rate limits](https://docs.permitcore.io/concepts/rate-limits.md) for the matrix + the
`X-RateLimit-*` response headers + the 429 problem+json shape.

## Example request

```bash theme={null}
curl "https://api.permitcore.io/v1/permits?jurisdiction=nyc&issued_after=2026-05-01&per_page=25" \
  -H "Authorization: Bearer $PERMITCORE_API_KEY" \
  -H "Accept: application/json"
```

## Related

* [Get a permit by canonical\_uid](https://docs.permitcore.io/api-reference/permits-by-canonical-uid.md) — the per-permit detail endpoint with full enrichment + nested `pluto`.
* [Cohort distribution](https://docs.permitcore.io/api-reference/jurisdictions/cohort-distribution.md) — aggregate counts behind these rows.
* [Free sandbox](https://permitcore.io/sandbox) — client-side DuckDB-WASM
  queries against the last 10 days of permits across the live metros. No
  signup, no API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.