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

# Quickstart

> Sign up, grab a key, make your first request. Five minutes.

## 1. Sign up for an API key

Magic-link signup at <a href="https://permitcore.io/signup">permitcore.io/signup</a>.
No credit card required for the free tier.

After signing in, your API key lives at <a href="https://permitcore.io/account/api-keys">Account → API Keys</a>.

Keys can be created and rotated via either the
<a href="https://permitcore.io/account/api-keys">account dashboard</a> or
the [programmatic key endpoints](/api-reference/keys).

## 2. Set up your environment

Export your key. Never commit it — treat it like a database password.

```bash theme={null}
export PERMITCORE_API_KEY=pk_...
```

## 3. Make your first request

Fetch the cohort distribution for New York City:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.permitcore.io/v1/jurisdictions/nyc/cohorts/distribution \
    -H "Authorization: Bearer $PERMITCORE_API_KEY" \
    -H "Accept: application/json"
  ```

  ```js Node.js theme={null}
  const res = await fetch(
    "https://api.permitcore.io/v1/jurisdictions/nyc/cohorts/distribution",
    {
      headers: {
        Authorization: `Bearer ${process.env.PERMITCORE_API_KEY}`,
        Accept: "application/json",
      },
    },
  );
  const data = await res.json();
  console.log(data.cohort_distribution);
  ```

  ```python Python theme={null}
  import os
  import httpx

  r = httpx.get(
      "https://api.permitcore.io/v1/jurisdictions/nyc/cohorts/distribution",
      headers={
          "Authorization": f"Bearer {os.environ['PERMITCORE_API_KEY']}",
          "Accept": "application/json",
      },
  )
  r.raise_for_status()
  print(r.json()["cohort_distribution"])
  ```
</CodeGroup>

## 4. Read the response

You'll get back the jurisdiction's canonical 18-cohort breakdown:

```json theme={null}
{
  "jurisdiction_slug": "nyc",
  "jurisdiction_display_name": "New York City, NY",
  "as_of_utc": "2026-05-24T02:00:00Z",
  "total_target_permits": 3218856,
  "cohort_distribution": {
    "multifamily_alteration": 2474522,
    "temporary_construction_support": 146420,
    "commercial_alteration": 119800,
    "multifamily_new": 73200,
    "commercial_demolition": 50100,
    "commercial_new": 38400,
    "commercial_mep": 27200,
    "commercial_signage": 18900,
    "residential_alteration": 14820,
    "residential_demolition": 9840,
    "residential_mep": 8400,
    "residential_new_sf": 6240,
    "commercial_pool": 3920,
    "industrial_new": 2840,
    "civic": 1820,
    "commercial_shell_only": 1200,
    "adu_qualifying": 380,
    "residential_foundation_only": 248
  }
}
```

`total_target_permits` is the **buyer-targeted matview slice** for the
jurisdiction — lifetime accumulation (no time window) of permits that
match PermitCore's matview filter (commercial / mixed / industrial work
classes, OR ≥5 residential units, OR explicit multifamily, OR qualifying
ADU). The sum of `cohort_distribution` values is **less than**
`total_target_permits` by the implicit NULL-segment count: permits that
pass the matview filter but didn't match any of the 18 cohort CASE
branches. For NYC, the full silver permit table holds \~7.63M permits
across all work types; the matview targets \~3.22M of those as the
buyer-relevant slice — see [the explainer in the API reference](/api-reference/jurisdictions/cohort-distribution#what-is-total_target_permits)
for the full data model.

All 18 canonical cohorts are always present (zero-filled if a jurisdiction
has no rows in that cohort).

## 5. What next

<CardGroup cols={2}>
  <Card title="Cohort taxonomy" icon="layer-group" href="/concepts/cohorts">
    The canonical 18 cohorts + what each one covers.
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    Key formats, header conventions, security best practices.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/concepts/rate-limits">
    Per-tier quotas + how to handle 429 responses.
  </Card>

  <Card title="Data licensing" icon="scale-balanced" href="/concepts/data-licensing">
    Commercial-use terms + attribution for paid tiers.
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/introduction">
    Full endpoint catalog with request/response shapes.
  </Card>
</CardGroup>

## Need help

* Open the [API reference](/api-reference/introduction) for endpoint
  shapes + the [errors page](/errors) for retry semantics.
* For account, billing, or integration support, email
  <a href="mailto:kian@permitcore.io">[kian@permitcore.io](mailto:kian@permitcore.io)</a> — include
  your key prefix (first 12 characters) and the `x-permitcore-request-id`
  from the failing response for fastest triage.