> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permits API

> Search US building permits by place and filters, count them for free, look permits up by id, and read coverage and vocabulary.

The Permits API returns US building permit records from public permit offices.
Every answer says how complete the data behind it is.

| Endpoint | Purpose | Access | Price |
| - | - | - | - |
| `POST /v1/permits/search` | Permits for one place and your filters, one page per call. | Licensed | Per permit, or per parcel for a parcel search |
| `GET /v1/permits?id=…` | 1 to 50 permits by id. | Licensed | Per permit found |
| `POST /v1/permits/stats` | Permit counts in one area, grouped by month, tag, category or office. See [Permits stats](https://docs.mireye.ai/api-reference/permits-stats.md). | Licensed | Per group returned |
| `POST /v1/permits/parcels` | One row per parcel with permits, in a county or for a list of parcels. See [Permits parcels](https://docs.mireye.ai/api-reference/permits-parcels.md). | Licensed | Per row returned |
| `GET /v1/permits/coverage` | Which permit offices in a state are collected. | Public | Free |
| `GET /v1/permits/vocabulary` | The values every filter accepts. | Public | Free |

> [!NOTE]
>
> * Each permit returned costs **\$0.012** on Free, **\$0.0086** on Build and
>   **\$0.0072** on Growth.
> * A parcel search page costs **\$0.036** on Free when it returns permits. One page
>   holds up to 100 of the parcel's permits.
> * Counts and empty answers are free. See [Price](#price) and [Pricing](https://docs.mireye.ai/pricing.md).
> * Search and lookup need accepted terms and licensed access with the `earth.search`
>   scope, the same scope as Search. See [Authentication](https://docs.mireye.ai/authentication.md).
> * Coverage and vocabulary need no API key.

Related pages:

* [Permits stats](https://docs.mireye.ai/api-reference/permits-stats.md): counts grouped by month, tag,
  category or office.
* [Permits parcels](https://docs.mireye.ai/api-reference/permits-parcels.md): one row per parcel with permits.
* [Permits coverage](https://docs.mireye.ai/api-reference/permits-coverage.md): what `complete`, `partial`
  and `not_collected` mean, and a coverage label for each state.
* [Permits known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md): what can be wrong in
  the data today, and how to work around it.
* [Search permits filter](https://docs.mireye.ai/api-reference/search-permits-filter.md): find parcels by
  their permits in `POST /v1/search`.
* [Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md): permit counts for one
  parcel in `POST /v1/enrich`.

## How to read an answer

Every search answer has two keys about completeness (an id lookup has them per permit):

* `coverage` is one word: `complete`, `partial` or `not_collected`. It is `null` when
  no permit office is known for the area.
* `note` is plain text, or `null`. It says what a count may miss. It can hold
  several sentences.

Rules:

* With `partial`, `not_collected` or `null` coverage, a count is a lower bound.
  A `0` is then not proof that no permits exist.
* A search by point, polygon, parcel or ZIP is never `complete`. It can see only the
  offices that have permits in the area. An office we do not collect can also serve
  the area.
* A source in the search may never record the date or status you filter on. Then
  coverage is never `complete`, on every page of the search. The `note` names the
  missing date or status.
* **Branch on `coverage` and `total`.** The `note` text is written for people and can
  change.

## Search permits

`POST /v1/permits/search`

### Example: solar permits in one county

```bash theme={null}
PERMITS_KEY="$(uuidgen)"   # keep this to retry the same request
curl -sS --max-time 60 https://api.mireye.com/v1/permits/search \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $PERMITS_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "where": {"state": "TX", "county_fips": "48157"},
    "filters": {
      "date_field": "issued",
      "date_from": "2025-01-01",
      "work_tags": ["solar"]
    },
    "limit": 1,
    "max_cost_usd": "0.20"
  }' | jq
```

```json theme={null}
{
  "permits": [
    {
      "permit_id": "pmt_tx_0a1b2c3d4e5f60718293a4b5",
      "permit_number": "BP-2025-004812",
      "office_name": "City of Example",
      "office_id": "tx:place:70808",
      "permit_type": "Residential Solar",
      "permit_subtype": null,
      "description": "Install 8.4 kW roof-mounted PV system",
      "status": "final",
      "filed_date": "2025-03-04",
      "issued_date": "2025-03-11",
      "finaled_date": "2025-04-22",
      "date_precision": "day",
      "earliest_date": "2025-03-04",
      "latest_date": "2025-04-22",
      "days_to_issue": 7,
      "days_issue_to_final": 42,
      "days_filed_to_final": 49,
      "valuation_usd": 24500,
      "fees_usd": 310.5,
      "work_tags": ["solar"],
      "work_tag_confidence": {"solar": 0.97},
      "street_number": "1234",
      "street_name": "EXAMPLE DR",
      "city": "Example",
      "zip": "77479",
      "zip4": null,
      "state": "TX",
      "state_fips": "48",
      "county_fips": "48157",
      "lat": 29.5901,
      "lng": -95.6402,
      "apn": "0001-00-000-0000-907",
      "status_detail": "finaled",
      "status_original": "Finaled",
      "date_flags": [],
      "valuation_flag": null,
      "fees_flag": null,
      "address": "1234 EXAMPLE DR, EXAMPLE, TX 77479",
      "category": "electrical",
      "category_original": "Electrical",
      "use_class": "residential",
      "detail_tags": ["solar"],
      "contractor_id": "ct:TX:7954f6ae5cec",
      "contractor_name": "EXAMPLE SOLAR LLC",
      "applicant_business": null,
      "sqft": null,
      "units": null,
      "undated": false,
      "location_method": "source",
      "parcel": {
        "parcel_id": "11111111-2222-3333-4444-555555555555",
        "join": "parcel_id",
        "confidence": "high"
      },
      "source": {
        "citation_url": "https://permits.example.gov/records",
        "attribution": null
      }
    }
  ],
  "total": 412,
  "next_cursor": "q9cS0k1u…",
  "coverage": "partial",
  "note": "Of the 21 permit offices here, 6 are complete, 3 are partly collected and 12 are not collected, so counts are a lower bound.",
  "billing": {
    "operation_id": "op_4b1d…",
    "currency": "USD",
    "charged_usd": "0.012000",
    "pricing_version": "earth-usd-v1",
    "replayed": false
  }
}
```

* Values are illustrative.
* Response headers include `X-Operation-Id` and `X-Mireye-Data-Version`. See
  [Headers](#headers).

### Example: the same search over hosted MCP

The tool is `mireye_permits_search`. Send the request body inside `req`:

```json theme={null}
{
  "req": {
    "where": {"state": "TX", "county_fips": "48157"},
    "filters": {"date_field": "issued", "date_from": "2025-01-01", "work_tags": ["solar"]},
    "limit": 1,
    "max_cost_usd": "0.20"
  },
  "idempotency_key": "tx-48157-solar-0001"
}
```

The tool returns the same body as REST: `permits`, `total`, `next_cursor`, `coverage`,
`note` and `billing`.

### Request shape

| Field | Type | Required | Default | Notes |
| - | - | - | - | - |
| `where` | object | yes | | Exactly one place selector. See [where](#where). |
| `filters` | object | no | `{}` | See [filters](#filters). |
| `sort` | string | no | `date_desc` | `date_desc`, `date_asc`, `valuation_desc` or `distance`. See [sort](#sort). |
| `limit` | integer | no | `25` | Permits per page, 0 to 100. `0` is a free count. See [Count for free](#count-for-free). |
| `cursor` | string | no | | The previous page's `next_cursor`. At most 2,000 characters. |
| `max_cost_usd` | decimal string | no | | Spending ceiling for this page, such as `"0.20"`. At most 20 characters. |

* Any other key, at any level, is rejected with `422`.
* Numbers must be JSON numbers. `true`, `"5"` and `NaN` are rejected.
* Text values are trimmed.

### where

Send exactly one of these shapes:

| Shape | Keys | Matches |
| - | - | - |
| Office | `authority_id` | Permits of one permit office, such as `"tx:place:70808"`. Get ids from [`GET /v1/permits/coverage`](#coverage). |
| City | `state`, `city` | Permits in that city, and permits of the city's own permit office. |
| County | `state`, `county_fips` | Permits in one county. `county_fips` is five digits, such as `"48157"`, and must be in `state`. |
| State | `state` | Permits in one state. |
| ZIP | `zip` | Permits whose address has this five-digit ZIP code, such as `"77479"`. |
| Near a point | `lat`, `lng`, `radius_m` | Permits whose map point is within `radius_m` metres. |
| Polygon | `geojson` | Permits whose map point is inside a GeoJSON `Polygon` or `MultiPolygon`. |
| Parcel | `parcel` | Permits tied to one parcel. See [Parcel selector](#parcel-selector). |
| Batch of parcels | `parcels` | 1 to 100 parcels in one call, each answered on its own. See [Batch of parcels](#batch-of-parcels). |

Limits:

* `state` is a two-letter code. The 50 states and DC are accepted.
* `city` is 1 to 120 characters. Case is ignored.
* `zip` is exactly five digits. A ZIP+4 is rejected. A ZIP search matches the
  permit's address, not its map point. So it also finds permits with no map point.
  Like a point search, it is never `complete`.
* `lat` is -90 to 90 and `lng` is -180 to 180.
* `radius_m` is above 0 and at most 50,000.
* A polygon has at most 2,000 positions and fits in a 1 degree by 1 degree box.
  Its rings are closed: the last position equals the first. Positions are
  `[lng, lat]` in WGS84. An empty, zero-area or self-crossing polygon is rejected.
* A point or polygon search matches only permits that have a map point. The `note`
  counts the permits it could not place.
* A parcel search also matches the permits tied to the parcel that have no map
  point. See [Parcel selector](#parcel-selector).

#### Parcel selector

`parcel` takes one of:

* `{"address": "…"}`: a street address, such as `"1234 Example Dr, Example, TX 77479"`.
  It is resolved the same way as in [Enrich](https://docs.mireye.ai/api-reference/enrich.md). See
  [Parcel by address](#parcel-by-address).
* `{"lat": …, "lng": …}`: the parcel that contains this point.
* `{"parcel_id": "…"}`: the parcel's id, a lowercase UUID such as
  `"11111111-2222-3333-4444-555555555555"`. It is the `parcel.parcel_id` of a permit
  record.

A parcel search returns the permits tied to the parcel, with or without a map point.
With an address or a point, it also returns permits whose map point is inside the
parcel.

The "no map location" sentence in the `note` can also appear on a parcel search. It
counts the permits without a map point in the offices that have permits here. Some of
them can still match through their parcel link.

* If no parcel contains the point, or more than one does, the answer is empty. The
  `note` says why, and the call is free. With several parcels, send a `parcel_id`.
* The same is true for an address that selects no single parcel.
* If a `parcel_id` search finds no permits, the call is free. The `note` says why:
  * When the parcel has linked permits that your filters left out: "Permits in this
    data are linked to this parcel\_id, but none match the filters. This search is not
    charged."
  * Otherwise: the id may be wrong, or the parcel may have no linked permits.

#### Parcel by address

An address goes through the same steps as an Enrich address: a geocode, the rooftop
rule, the parcel match and the unit tie-break.

* The answer has two more keys: `geocode` (how the address was geocoded) and `parcel`.
  `parcel` holds `status` (`matched`, `ambiguous` or `no_match`), `parcel_id`,
  `match_type`, `address`, `candidates` (a count) and `reason`.
* When the address selects no single parcel, the answer has no permits. The `note`
  says why, and the call is free. For example: "More than one parcel matches this
  address; send a parcel\_id."
* In some buildings, the units share one parcel outline. When the address names one
  such unit, only the permits linked to that unit are returned. The `note` says so.
* An address the geocoder cannot use returns the same errors as an Enrich address.
  See [Enrich](https://docs.mireye.ai/api-reference/enrich.md).

### filters

| Key | Type | Default | Meaning |
| - | - | - | - |
| `date_field` | string | `earliest` | The date the date bounds and date sorts use: `filed`, `issued`, `finaled` or `earliest`. See [Dates](#dates). |
| `date_from` | date | | `date_field` on or after this date. |
| `date_to` | date | | `date_field` on or before this date. Not before `date_from`. |
| `earliest_from` | date | | `earliest_date` on or after this date. |
| `latest_to` | date | | `latest_date` on or before this date. Not before `earliest_from`. |
| `issued_since` | date | | `issued_date` on or after this date. Leaves out re-issued permits. See [Re-issued permits](#re-issued-permits). |
| `updated_since` | date or date-time | | Permits whose record changed on or after this date. A time is ignored. |
| `status` | list | | `in_review`, `active`, `final`, `inactive` or `unknown`. Matches the record's `status`. |
| `category` | list | | See [Vocabulary](#vocabulary). |
| `use_class` | list | | `residential`, `commercial`, `mixed` or `unknown`. |
| `work_tags` | list | | Work tags such as `solar` or `roof`. A parent tag also matches its child tags: `electrical` matches `solar`. |
| `detail_tags` | list | | The wider detail tag list. 1 to 40 lowercase letters, digits or underscores each, such as `solar`. |
| `tags_match` | string | `any` | `any`: a permit needs one of the listed tags. `all`: it needs every listed tag. Applies to `work_tags` and `detail_tags`. |
| `valuation_min_usd` | number | | Valuation at or above this, in US dollars (not cents). At least 0. |
| `valuation_max_usd` | number | | Valuation at or below this, in US dollars. Not below `valuation_min_usd`. |
| `exclude_flagged_valuation` | boolean | `false` | Leave out permits whose `valuation_flag` is set. |
| `contractor` | string | | Contractor name contains this text. 2 to 120 characters. Case is ignored. |
| `contractor_id` | string | | A permit's `contractor_id`, exactly. |
| `include_undated` | boolean | `false` | Also return permits with no date. See [Dates](#dates). |
| `include_history` | boolean | `false` | Also return records dated before July 1, 2024. See [History](#history). |
| `include_reissued` | boolean | `false` | Keep re-issued permits in "new since" searches. See [Re-issued permits](#re-issued-permits). |
| `min_date_precision` | string | | `day`, `month` or `year`. Only permits whose dates are at least this exact. `month` matches `day` and `month`. A permit with an unknown precision does not match. |

* Dates are `YYYY-MM-DD`.
* Lists take 1 to 20 values. An empty list is rejected, except `status`, `category`
  and `work_tags`, where `[]` means no filter.
* An unknown `status`, `category`, `use_class` or `work_tags` value is rejected. The
  error names the nearest valid values, such as `Did you mean pool_spa?`.
* `detail_tags` values are not checked against the vocabulary. An unknown detail tag
  is accepted and matches no permit. Check the values in
  [`GET /v1/permits/vocabulary`](#vocabulary) first.
* `status` filters on the record's `status`. The source's finer status is in
  `status_detail`.
* A valuation range leaves out permits whose source gives no valuation. The `note`
  counts them.

#### Dates

A permit can have three dates: `filed_date`, `issued_date` and `finaled_date`.

* `earliest_date` is the earliest of the three. When a permit has none of them, it is
  the date we first saw the permit. Then `undated` is `true`.
* `latest_date` is the latest of the three.
* `date_field` names the date the bounds apply to:
  * `filed`, `issued` and `finaled` return only permits that have that date, with or
    without bounds. Exception: with `include_undated: true`, permits with no date are
    returned too.
  * `earliest` (the default) applies the bounds to `earliest_date`.
* Undated permits are left out unless `include_undated` is `true`. The `note` says how
  many were left out.
* Dates match as stored. `date_precision` says how exact they are:
  * `day`: an exact date.
  * `month`: the source gives the month only. The date is the 1st of that month.
  * `year`: the source gives the year only. The date is January 1 of that year.
  * `null`: not known.
* A search on a milestone that a source never records cannot match that source's
  permits. The `note` says so: for those offices a `0` does not mean none happened.

#### History

By default the API returns the permits issued on or after July 1, 2024. A permit with
no issued date counts by its filed date.

* Such a permit can have a filed date, and so an `earliest_date`, before July 1, 2024.
  An `earliest` search with no date bounds returns it.
* `include_history: true` also returns older records where we have them.
* A history record has the same fields. It was issued before July 1, 2024, or, with
  no issued date, filed before that date.
* When the data holds no history records, the `note` says the filter has no data yet.

#### Re-issued permits

A re-issued permit is an old permit issued again. It is not new work. It is issued on
or after July 1, 2024, and either:

* it was filed more than 5 years before that issue date, or
* it was finaled more than 1 year before that issue date.

How the API treats it:

* Its `date_flags` holds `"reissued"`.
* `issued_since`, and `date_field: "issued"` with a `date_from`, leave it out. The
  `note` says how many were left out.
* Set `include_reissued: true` to keep it in those searches.
* Every other search returns it. `earliest` and `filed` searches use its old dates.

### sort

| Value | Order |
| - | - |
| `date_desc` | Newest `date_field` date first. |
| `date_asc` | Oldest `date_field` date first. |
| `valuation_desc` | Highest valuation first. |
| `distance` | Nearest first. Needs the near-a-point selector. |

* Permits with no value for the sort key come last in either direction.
* Ties are ordered by `permit_id`.

### Response

| Key | Type | Meaning |
| - | - | - |
| `permits` | array | This page's permit records. See [Permit record](#permit-record). |
| `total` | integer | Every permit that matches, on all pages. |
| `next_cursor` | string or `null` | Send it as `cursor` for the next page. `null` on the last page. |
| `coverage` | string or `null` | `complete`, `partial`, `not_collected` or `null`. See [How to read an answer](#how-to-read-an-answer). |
| `note` | string or `null` | What the counts may miss, in plain sentences. |
| `billing` | object | The receipt: `operation_id`, `currency`, `charged_usd`, `pricing_version`, `replayed`. |
| `geocode`, `parcel` | object | Only on a parcel search by address. See [Parcel by address](#parcel-by-address). |

* `total` counts permit records, not unique permits. Some jobs are filed as several
  linked records. An example is a New York City job and its work permits. Here each
  record counts once. Undated and history records reported by two sources can also
  count twice. Dated permits from July 1, 2024 are already merged across sources, with the
  exceptions in [known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md).
* The Search permits filter and the Enrich permit fields count unique permits: each
  linked job and each merged permit counts once. So `total` for a parcel can be higher
  than `permits_matched` or `parcel_permit_count`.
* `coverage` describes the offices of the whole search, on every page. A milestone
  that a source never records keeps it below `complete` on every page too.

### Count for free

Send `limit: 0` to count without permits. It is not charged.

* While it runs, one permit row (**\$0.012** on Free) is held and then released.
* Your balance and `max_cost_usd` must cover that hold.

The answer has:

* `total`, `coverage` and `note`;
* an empty `permits` list;
* `next_cursor: null`.

```json theme={null}
{
  "where": {"zip": "77479"},
  "filters": {"date_field": "issued", "date_from": "2025-01-01", "work_tags": ["solar"]},
  "limit": 0
}
```

* A count takes no `cursor`. `limit: 0` with a `cursor` is rejected with `422`.
* Count first, then pay for pages only when the count is worth it.

### Paging

* `next_cursor` is `null` on the last page.
* Send it as `cursor` with the same `where`, `filters` and `sort`. `limit` and
  `max_cost_usd` may change.
* A cursor expires after one hour.
* A cursor also expires when the permit data is refreshed. Start again without a
  cursor. Check `X-Mireye-Data-Version` to see the data version.
* Each page is a new paid call with its own `Idempotency-Key`.

### note sentences

The `note` joins these sentences. The numbers below are examples.

| When | Sentence | Details |
| - | - | - |
| Some offices are not complete | "Of the 21 permit offices here, 6 are complete, 3 are partly collected and 12 are not collected, so counts are a lower bound." | A point, polygon, parcel or ZIP search says "permit offices with permits in this area". |
| No office is collected | "No permit office here is collected yet, so a 0 is not proof that no permits exist." | |
| Point, polygon, parcel or ZIP search | "An area search sees only permit offices with permits in the area; an office we do not collect may also serve it, so counts are a lower bound." | |
| A point, polygon, parcel or ZIP search matches nothing, and collected offices have permits in the area | "City of Example is collected; no permits match these filters." | This sentence replaces the first sentence above. It names up to 3 offices. For example: "City of A is collected and City of B is partly collected; no permits match these filters.". With more than 3, it counts them: "5 permit offices with permits here are collected; no permits match these filters." |
| A point, polygon, parcel or ZIP search matches nothing, and no office in the area has permits | "No collected permit office has permits in this area; it may be served by an office we do not collect yet." | |
| A point, polygon, parcel or ZIP search matches nothing, and we cannot tell which offices have permits there | "No permits match these filters in this area." | |
| Undated permits left out | "1,204 permits have no date and were left out; set include\_undated to get them." | |
| Re-issued permits left out | "38 re-issued permits (issued in range, filed more than 5 years or finaled more than 1 year before) were left out; set include\_reissued to true to include them." | |
| A source never records the date or status | "2,310 permits could not match because their source never records a filing date; for those offices a 0 does not mean none happened." | The words are "a filing date", "an issue date" or "a final date". For a `final` status filter, they are "a final status". |
| Valuation range | "512 permits were left out because their source gives no valuation." | |
| Permits with no map point | "75 permits in these offices have no map location and cannot match an area search." | On a parcel search, permits tied to the parcel can still match without a map point. |
| A filter has no data yet | "The filter filters.detail\_tags has no data yet, so it matches nothing." | |
| A parcel point matches no parcel | "No parcel contains this point." | |
| A parcel point matches several parcels | "More than one parcel contains this point; send a parcel\_id." | |
| A parcel address matches several parcels | "More than one parcel matches this address; send a parcel\_id." | |
| A parcel address matches no parcel | The reason, as Enrich gives it. | For example, an address that is not geocoded to a rooftop. |
| A parcel address names one unit | "This address names one unit of a building whose units share one outline, so only the permits linked to this unit are listed. Permits for the building as a whole, or for other units, are not." | |
| A `parcel_id` search finds nothing, and the parcel has linked permits | "Permits in this data are linked to this parcel\_id, but none match the filters. This search is not charged." | |
| A `parcel_id` search finds nothing, and the parcel has no linked permits | "No permits in this data are linked to this parcel\_id and match the filters. The id may be wrong, or the parcel may have no linked permits. This search is not charged." | |

When a count is not known, the sentence starts with "Some". A count of 1 is
singular: "1 permit has no date and was left out; set include\_undated to get them."

## Batch of parcels

Send `where.parcels` to read the permits of up to 100 parcels in one call. Each entry
is a [parcel selector](#parcel-selector): `{"address": …}`, `{"lat": …, "lng": …}` or
`{"parcel_id": …}`. Each one is answered exactly as its own single parcel search.

```bash theme={null}
curl -sS --max-time 90 https://api.mireye.com/v1/permits/search \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "where": {"parcels": [
      {"parcel_id": "11111111-2222-3333-4444-555555555555"},
      {"address": "1234 Example Dr, Example, TX 77479"}
    ]},
    "filters": {"work_tags": ["roof"]},
    "limit_per_parcel": 10,
    "max_cost_usd": "0.20"
  }' | jq
```

```json theme={null}
{
  "parcels": [
    {
      "input": 0,
      "status": "matched",
      "permits": [{"permit_id": "pmt_tx_0a1b2c3d4e5f60718293a4b5", "…": "the full permit record"}],
      "total": 1,
      "coverage": "partial",
      "note": "An area search sees only permit offices with permits in the area; an office we do not collect may also serve it, so counts are a lower bound.",
      "next": null
    },
    {
      "input": 1,
      "status": "ambiguous",
      "permits": [],
      "total": 0,
      "coverage": null,
      "note": "More than one parcel matches this address; send a parcel_id.",
      "next": null
    }
  ],
  "summary": {
    "inputs": 2,
    "matched": 1,
    "with_permits": 1,
    "not_matched": 1,
    "unavailable": 0,
    "time_limit_reached": 0
  },
  "billing": {
    "operation_id": "op_4b1d…",
    "currency": "USD",
    "charged_usd": "0.036000",
    "pricing_version": "earth-usd-v1",
    "replayed": false
  }
}
```

Values are illustrative.

Request rules:

* `parcels` holds 1 to 100 entries. `filters` and `sort` apply to every parcel.
* `limit_per_parcel` is the most permits per parcel, 0 to 100. The default is 25. `0`
  counts each parcel's permits without returning them, for free.
* A batch takes no `limit` and no `cursor`. Each is rejected with `422`.

Each entry of `parcels` in the answer, in the order you sent:

| Key | Meaning |
| - | - |
| `input` | The entry's position in your list, from 0. |
| `status` | `matched`, `no_match`, `ambiguous`, `refused`, `unavailable` or `time_limit_reached`. See below. |
| `permits`, `total`, `coverage`, `note` | The same as a single parcel search for this entry. |
| `next` | The single parcel search that continues this parcel: `where`, `filters`, `sort` and `limit` (values at their default are left out) and `cursor`. Send it as is to `POST /v1/permits/search`. `null` when there are no more permits. |
| `geocode`, `parcel` | Only for an address entry. See [Parcel by address](#parcel-by-address). |
| `error` | Only for `refused`, `unavailable` and `time_limit_reached`: `error`, `message` and `retryable`. |

| `status` | Meaning |
| - | - |
| `matched` | One parcel. Its permits were read. |
| `no_match` | The address or point selects no parcel. The `note` says why. |
| `ambiguous` | Several parcels match. Send a `parcel_id`. |
| `refused` | The address cannot be used as sent, for example a PO box. `error` says why. |
| `unavailable` | Address or parcel matching was down for this entry. Send it again. |
| `time_limit_reached` | The call ran out of time before this entry. Send it again. |

`summary` counts the entries:

* `inputs`
* `matched`
* `with_permits`: parcels with at least one permit that matches the filters. It is
  filled in a count (`limit_per_parcel: 0`) too.
* `not_matched`: `no_match`, `ambiguous` and `refused`.
* `unavailable`
* `time_limit_reached`

Price and failures:

* A batch costs one permit property (**\$0.036** on Free) for each distinct parcel
  that returns a permit. The same parcel sent twice is charged once.
* A parcel with no permits, an entry that is not matched and a count
  (`limit_per_parcel: 0`) cost nothing.
* When parcel matching is down for every entry, the whole call fails with `503
  parcel_unavailable` and `retryable: true`. Send it again with the same
  `Idempotency-Key`.

## Look up permits by id

`GET /v1/permits?id=…` returns 1 to 50 permits by their `permit_id`, such as
`pmt_tx_0a1b2c3d4e5f60718293a4b5`. Repeat `id` for each permit.

### Example

```bash theme={null}
curl -sS --max-time 60 -G https://api.mireye.com/v1/permits \
  --data-urlencode "id=pmt_tx_0a1b2c3d4e5f60718293a4b5" \
  --data-urlencode "id=pmt_tx_ffffffffffffffffffffffff" \
  --data-urlencode "max_cost_usd=0.20" \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" | jq
```

```json theme={null}
{
  "permits": [
    {
      "permit_id": "pmt_tx_0a1b2c3d4e5f60718293a4b5",
      "permit_number": "BP-2025-004812",
      "office_name": "City of Example",
      "status": "final",
      "issued_date": "2025-03-11",
      "…": "the full permit record",
      "coverage": "partial",
      "note": "This permit's office is partly collected."
    }
  ],
  "missing": ["pmt_tx_ffffffffffffffffffffffff"],
  "billing": {
    "operation_id": "op_7c2e…",
    "currency": "USD",
    "charged_usd": "0.012000",
    "pricing_version": "earth-usd-v1",
    "replayed": false
  }
}
```

Values are illustrative.

### Example over hosted MCP

The tool is `mireye_permits_get`. Its arguments are top level, not inside `req`:

```json theme={null}
{
  "permit_ids": ["pmt_tx_0a1b2c3d4e5f60718293a4b5"],
  "max_cost_usd": "0.20",
  "idempotency_key": "permit-lookup-0001"
}
```

### Request and response

| Parameter | Where | Notes |
| - | - | - |
| `id` | query | A `permit_id`: `pmt_`, a two-letter state code and 24 hexadecimal characters. Repeat it for more permits: 1 to 50 in all. A repeated id is answered once. Over MCP the list is `permit_ids`. |
| `max_cost_usd` | query | Optional spending ceiling, such as `0.20`. |

| Key | Meaning |
| - | - |
| `permits` | The found permits, in the order you asked. Each is a [permit record](#permit-record) with two more keys, `coverage` and `note`. See below. |
| `missing` | The ids not found, in the order you asked. `[]` when every id was found. |
| `billing` | The receipt. |

The two extra keys on each found permit:

| Key | Value |
| - | - |
| `coverage` | The word for the permit's office. `null` when the office is not known. |
| `note` | "This permit's office is partly collected." when `coverage` is `partial`. Else `null`. |

* A lookup costs one permit row (**\$0.012** on Free) for each permit found.
* When no id is found, the answer is `permits: []` with every id in `missing`, and it
  is not charged.
* A malformed id, no id, or more than 50 ids is rejected with `422
  permits_invalid_request` before any charge. `problems` names the bad `id` entry.

## Permit record

* Every key except `distance_m` is always present.
* A missing value is `null`.
* In an id lookup, each permit also has `coverage` and `note`.

| Key | Meaning |
| - | - |
| `permit_id` | Our id for the permit. Stable while the permit stays in the data. |
| `permit_number` | The office's permit number. |
| `office_name`, `office_id` | The permit office and its id. The id works in `where.authority_id`. |
| `permit_type`, `permit_subtype` | The type and subtype as the source writes them. |
| `description` | The source's description of the work. |
| `status` | `in_review`, `active`, `final`, `inactive` or `unknown`. |
| `status_detail` | The finer status: `applied`, `issued`, `finaled`, `expired_void` or `unknown`. |
| `status_original` | The status as the source writes it. |
| `filed_date`, `issued_date`, `finaled_date` | The three milestones. See [Dates](#dates). |
| `date_precision` | `day`, `month`, `year` or `null` (not known). |
| `earliest_date`, `latest_date` | The earliest and latest of the three dates. |
| `days_to_issue` | Days from filed to issued. `null` when a date is missing, out of order or not exact to the day. |
| `days_issue_to_final` | Days from issued to finaled. `null` when a date is missing, out of order or not exact to the day. |
| `days_filed_to_final` | Days from the earliest to the latest of the three dates, whatever their order. `0` when the permit has only one date. `null` when the permit has no date or its dates are not exact to the day. |
| `valuation_usd` | The declared value of the work, in US dollars. |
| `fees_usd` | The fees, in US dollars. |
| `valuation_flag`, `fees_flag` | Set when the value looks wrong. The value itself is never changed. Current values include `zero_reported`, `extreme`, `repeated`, `token` and `implausible_for_category`. `fees_flag` uses `zero_reported` and `extreme`. |
| `date_flags` | Date checks. See below. `[]` when there is none. |
| `work_tags` | Work tags, assigned by Mireye from the permit's own text. They can be wrong. |
| `work_tag_confidence` | Per work tag, the share of permits with that tag that were correct in a hand-checked random sample. `null` means not measured. |
| `detail_tags` | The wider detail tags, or `null` when the permit has not been tagged. |
| `category`, `category_original` | Our category, and the category as the source writes it. |
| `use_class` | `residential`, `commercial`, `mixed` or `unknown`. |
| `address`, `street_number`, `street_name`, `city`, `zip`, `zip4` | The permit's address. |
| `state`, `state_fips`, `county_fips` | Where the permit is. |
| `lat`, `lng` | The permit's map point. |
| `location_method` | How the map point was found. See below. |
| `apn` | The parcel number as the source writes it. |
| `parcel` | The parcel the permit is tied to: `parcel_id`, `join` and `confidence`. `null` when it is not tied to a parcel. |
| `contractor_id`, `contractor_name` | The contractor. `contractor_id` works in `filters.contractor_id`. |
| `applicant_business` | The applicant's business name. |
| `sqft`, `units` | Floor area in square feet and dwelling units, when the source gives them. |
| `undated` | `true` when the permit has no filed, issued or finaled date. |
| `distance_m` | Metres from the search point. Only on a near-a-point search. |
| `source` | `citation_url`: where the record came from. `attribution`: text you must show with the data, or `null`. |

`location_method` values:

* `source`: the source gives it.
* `parcel`: the linked parcel.
* `address`: an address match to a parcel.
* `census`: a public address geocoder.

`parcel.join` says how the permit was tied to the parcel:

* `parcel_id`: the permit names the parcel's number.
* `point_in_parcel`: the permit's map point is inside the parcel.
* `address`: the permit's address matches the parcel's.

`parcel.confidence` is `high` or `medium`.

`date_flags` values:

| Value | Meaning |
| - | - |
| `issue_before_file` | The issued date is before the filed date. |
| `final_before_issue` | The finaled date is before the issued date. |
| `final_before_file` | The finaled date is before the filed date. |
| `coarse_date` | The dates are month or year only. |
| `finaled_placeholder_removed` | The source gave a placeholder finaled date. It was removed. |
| `reissued` | A re-issued permit. See [Re-issued permits](#re-issued-permits). |

## Coverage

`GET /v1/permits/coverage` lists which permit offices in one state are collected. Public: no API key, no charge.

### Example

```bash theme={null}
curl -sS "https://api.mireye.com/v1/permits/coverage?state=TX&county_fips=48157" | jq
```

```json theme={null}
{
  "as_of": "2026-11-17",
  "state": "TX",
  "summary": {"complete": 6, "partial": 3, "not_collected": 12},
  "coverage_words": {
    "complete": "The office's permit records are collected in full.",
    "partial": "Collected, but the feed is partial or covers only some permit types; counts are a lower bound.",
    "not_collected": "Not collected yet; a 0 here is not proof that no permits exist."
  },
  "offices": [
    {
      "id": "tx:place:70808",
      "name": "City of Example",
      "state": "TX",
      "type": "city",
      "county_fips": "48157",
      "dates_covered": {"from": "2024-07-01", "to": "2026-11-10"},
      "last_refresh": "2026-11-10T19:33:00Z",
      "permits": 18234,
      "undated_permits": 12,
      "permits_with_location": 18101,
      "reissued_permits": 41,
      "coverage": "complete",
      "sources": [
        {"citation_url": "https://permits.example.gov/records", "attribution": null}
      ]
    }
  ]
}
```

There is no MCP tool for coverage. Agents can call this HTTPS endpoint directly: it
needs no key.

### Query parameters

| Parameter | Required | Notes |
| - | - | - |
| `state` | yes | Two-letter code. The 50 states and DC. |
| `county_fips` | no | Five digits, in `state`. |
| `authority_id` | no | One office id. |
| `status` | no | `complete`, `partial` or `not_collected`. Lists only offices with that word. `summary` still counts every office. |

### Response

| Key | Meaning |
| - | - |
| `as_of` | The date the permit data was built. |
| `state` | The state asked for. |
| `summary` | Offices per coverage word. Words with no office are left out. |
| `coverage_words` | What each word means. |
| `offices` | One entry per office. |

Each office:

| Key | Meaning |
| - | - |
| `id` | The office id. Use it in `where.authority_id`. |
| `name`, `state`, `county_fips` | The office and where it is. |
| `type` | `city` or `county_unincorporated` (the county's office for areas outside cities). |
| `dates_covered` | `{from, to}`: the dates of the permits we hold, or `null`. |
| `last_refresh` | When the office's data was last collected. |
| `permits` | Dated permits we serve for the office, issued on or after July 1, 2024. A permit with no issued date counts by its filed date. Undated permits and history records are not in this count. |
| `undated_permits` | Permits with no date. |
| `permits_with_location` | Records of every kind with a map point: dated permits, undated permits and history records. It is not a share of `permits` and can be higher than `permits`. |
| `reissued_permits` | Of `permits`, the re-issued ones. |
| `coverage` | `complete`, `partial` or `not_collected`. |
| `sources` | Each source: `citation_url` and `attribution`. |

See [Permits coverage](https://docs.mireye.ai/api-reference/permits-coverage.md) and
[Permits known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md).

## Vocabulary

`GET /v1/permits/vocabulary` lists the values the search filters accept, and the measured confidence of each tag. Public:
no API key, no charge.

### Example

```bash theme={null}
curl -sS https://api.mireye.com/v1/permits/vocabulary | jq '{work_tags, work_tag_hierarchy}'
```

```json theme={null}
{
  "work_tags": [
    "addition", "adu", "bathroom", "battery", "demolition", "electric_meter",
    "electrical", "ev_charger", "fire_sprinkler", "gas", "generator", "grading",
    "heat_pump", "hvac", "kitchen", "new_building", "plumbing", "pool_spa",
    "remodel", "roof", "solar", "telecom", "water_heater", "window_door"
  ],
  "work_tag_hierarchy": {
    "electrical": ["solar", "ev_charger", "battery", "electric_meter"],
    "hvac": ["heat_pump"],
    "plumbing": ["water_heater"]
  }
}
```

There is no MCP tool for the vocabulary. Agents can call this HTTPS endpoint directly.

### Response

| Key | Meaning |
| - | - |
| `statuses` | Values of `status` and `filters.status`. |
| `status_details` | Values of `status_detail`. |
| `work_tags` | Values of `work_tags` and `filters.work_tags`. |
| `work_tag_hierarchy` | Parent tag to child tags. A parent filter also matches its children. |
| `work_tag_confidence` | Per work tag, the measured share correct, or `null` when not measured. |
| `work_tag_beta` | Per work tag, `true` when the tag is beta (less reliable), else `false` or `null`. |
| `detail_tags` | The detail tags and their measured confidence. |
| `date_fields` | `filed`, `issued`, `finaled`, `earliest`. |
| `sorts` | Values of `sort`. |
| `categories` | Values of `category` and `filters.category`: `new_residential`, `new_commercial`, `residential_alteration`, `commercial_alteration`, `demolition`, `electrical`, `plumbing`, `mechanical`, `other`. |
| `use_classes` | Values of `use_class`. |
| `location_methods` | Values of `location_method`. |
| `coverage_words` | What each coverage word means. |
| `where` | The `where` shapes. |
| `money` | `"USD dollars (not cents)"`. |

## Headers

| Header | On | Meaning |
| - | - | - |
| `X-Mireye-Data-Version` | Every answer | The version of the permit data that made it. A replayed page keeps its own version. Quote it to support. |
| `X-Operation-Id` | Search and lookup | The paid operation id. |
| `Cache-Control` | Every answer | `private, no-store` on search and lookup. `public, max-age=300` on coverage and vocabulary. |

## Price

You pay for what a call returns:

| | Free | Build | Growth |
| - | -: | -: | -: |
| Permit row: each permit from an area search or an id lookup | \$0.012 | \$0.0086 | \$0.0072 |
| Permit property: each parcel whose permits a parcel search or batch returns | \$0.036 | \$0.026 | \$0.0216 |

* A parcel search page (by address, point or `parcel_id`) is one property, up to 100
  permits. Each further page of the same parcel is one more property.
* The most a call can return is reserved first. Set `max_cost_usd` at or above it. See
  [Pricing](https://docs.mireye.ai/pricing.md#permits).

These are free:

* a count (`limit: 0`);
* a page with no permits;
* a batch of parcels in which no parcel returns a permit;
* a parcel address or point that selects no single parcel;
* a `parcel_id` search that finds no permits;
* an id lookup that finds no permit;
* an unknown `authority_id` (`404 office_not_found`);
* a call that fails;
* `GET /v1/permits/coverage` and `GET /v1/permits/vocabulary`.

## Retries

* Send a stable `Idempotency-Key` header for each search page and each lookup.
* The key is 8 to 128 characters: letters, digits, `_`, `.`, `:` or `-`.
* The same key with the same request returns the saved answer and its receipt. There
  is no second charge.
* Reusing a key for a changed request returns `409 idempotency_conflict`.
* A paid call that fails after it starts finishes its key. The same key then returns
  the same failure. Send a new key. See [Errors](#errors).
* Hosted MCP takes the same value as `idempotency_key`.

## Errors

Errors return `detail.error`, `detail.message` and, for most, `detail.retryable`:

```json theme={null}
{
  "detail": {
    "error": "permits_invalid_request",
    "message": "The permits request is not valid.",
    "problems": [
      {"path": "where", "message": "Value error, where takes exactly one selector: {authority_id}, {state, city}, {state, county_fips}, {state}, {lat, lng, radius_m}, {geojson}, {parcel}, {zip} or {parcels}"}
    ],
    "retryable": false
  }
}
```

| HTTP | Code | Retry | Meaning |
| - | - | - | - |
| 422 | `permits_invalid_request` | no | The request is not valid. `problems` lists up to 10 `{path, message}` items. A body that is not JSON gets the message "The body must be JSON." and no `problems`. |
| 422 | `permits_cursor_invalid` | no | The cursor is not valid for this request. |
| 422 | `permits_cursor_expired` | no | The cursor expired, or the permit data was refreshed. Start again without a cursor. |
| 422 | `permits_duplicate_id` | no | The permit data holds this `permit_id` twice. Not charged. Report it with the `permit_id`. |
| 404 | `office_not_found` | no | No permit office has this `authority_id`. See `GET /v1/permits/coverage`. Not charged. |
| 410 | `permits_withdrawn` | no | A saved answer holds permits from a source we may no longer serve. Not charged. Run the request again for the current permits. The body also has `sources`, the ids of the withdrawn sources, and `operation_id` when it is known. |
| 429 | `permits_busy` | yes | Permit search is at capacity. Wait for `Retry-After` (2 seconds), then send the same request with the same `Idempotency-Key`. |
| 429 | `permits_rate_limited` | yes | Coverage or vocabulary: more than 60 requests a minute from one IP address. Wait for `Retry-After`. |
| 503 | `permits_unavailable` | see below | The permit data is not available right now. |
| 503 | `parcel_unavailable` | see below | Parcel matching for a parcel address or point is not available. |
| 504 | `permits_timeout` | no | The search took too long. Not charged. Narrow it, or send it again with a new `Idempotency-Key`. |

Two kinds of failure:

* **Before the paid call starts.** `permits_busy`, and `permits_unavailable` or
  `parcel_unavailable` with `retryable: true`. The response has `Retry-After`
  (`permits_unavailable`: 30 seconds, `parcel_unavailable`: 5 seconds). Wait, then
  send the same request with the same `Idempotency-Key`.
* **After the paid call starts.** `permits_timeout`, and `permits_unavailable` or
  `parcel_unavailable` with `retryable: false`. Nothing is charged, but the
  `Idempotency-Key` is finished: the same key returns the same failure. The response
  has no `Retry-After`. To try again, send the request with a new `Idempotency-Key`.

Branch on `retryable`, not on the code alone.

Search and lookup also return the shared account, billing and rate-limit errors. See
[Errors](https://docs.mireye.ai/api-reference/errors.md). For example:

* `401 auth_missing`
* `403 terms_required`
* `402 max_cost_too_low`
* `402 insufficient_balance`
* `409 idempotency_conflict`
* `429 rate_limited`

Do not retry an unchanged `422`.

## Data and terms

* Permits come from public records published by permit offices.
* Some sources are held back until their terms let us serve them. Their permits are
  not in any answer or count.
* Show a source's `attribution` text wherever you show its permits.
* Work tags and parcel links are made by Mireye. They can be wrong. Read
  `work_tag_confidence` and `parcel.confidence`.
