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

# API reference overview

> Base URL, versioning, auth conventions, and the endpoint catalog.

## Base URL

```
https://api.permitcore.io
```

All endpoints are versioned under `/v1`. Breaking changes ship as `/v2` —
no surprise mutations.

## Auth

Every request must include:

```http theme={null}
Authorization: Bearer <your-api-key>
```

See [Authentication](/authentication) for key formats + security guidance.

## Response format

JSON in, JSON out. All responses use UTF-8. Timestamps are ISO 8601 with
UTC offset (`Z`). Numeric IDs are strings to avoid 53-bit precision loss
in JavaScript.

```json theme={null}
{
  "as_of_utc": "2026-05-24T02:00:00Z",
  "total_target_permits": 3218856,
  "cohort_distribution": { "...": 0 }
}
```

## Errors

Every non-2xx response follows this shape:

```json theme={null}
{
  "error": {
    "code": "missing_credentials",
    "message": "Missing Authorization: Bearer <key> header.",
    "detail": null
  }
}
```

See [Errors](/errors) for the full code catalog + retry guidance.

## Endpoint catalog

<CardGroup cols={1}>
  <Card title="Cohort distribution" icon="chart-pie" href="/api-reference/jurisdictions/cohort-distribution">
    `GET /v1/jurisdictions/{slug}/cohorts/distribution` — per-jurisdiction
    breakdown across the canonical 18 cohorts. Cached 1 hour upstream.
    **Live today.**
  </Card>

  <Card title="Permits (list + filter)" icon="database" href="/api-reference/permits">
    `GET /v1/permits?jurisdiction=&cohort=&issued_after=…` — paginated permit
    rows with field-level DQ flags. **Live today.**
  </Card>

  <Card title="Jurisdiction overview" icon="map" href="/api-reference/jurisdictions/overview">
    Resource overview + jurisdiction list endpoint contracts.
  </Card>

  <Card title="API key management" icon="key" href="/api-reference/keys">
    `POST /v1/keys`, `DELETE /v1/keys/{prefix}`, `GET /v1/keys/{prefix}/usage`
    — programmatic key lifecycle. **Live today.**
  </Card>
</CardGroup>

## OpenAPI specification

The OpenAPI 3.1 schema is exposed at `https://api.permitcore.io/openapi.json`
— FastAPI-generated from the deployed code, so it always reflects the
authoritative request/response shapes. This reference page remains the
canonical narrative source.

## Support

Email <a href="mailto:kian@permitcore.io">[kian@permitcore.io](mailto:kian@permitcore.io)</a> for
account, billing, or integration questions on any tier. Enterprise tier
includes a custom SLA on contact.

For incidents, watch the [changelog](/changelog) — outage notes land
there in real time.