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

# Jurisdictions & State Codes

> The jurisdictions the API accepts, how state codes and the federal jurisdiction work, and the two endpoints that tell you what is actually there

`state` accepts **56 US jurisdictions**: all 50 states, plus the District of
Columbia, Puerto Rico, Guam (`gu`), the Northern Mariana Islands (`mp`), the US
Virgin Islands (`vi`) and American Samoa (`as`).
Federal law lives under its own `federal` jurisdiction, separate from the states.

Accepting a jurisdiction is not the same as holding every corpus for it, so read
`GET /us/statutes/coverage` before you scope a search.

## How jurisdictions are keyed

* **State codes** are 2-letter strings: `ca`, `tx`, `ny`, `fl`, and so on.
  They are case-insensitive, and an unrecognized value is rejected with a 422
  rather than silently matching nothing.
* Pass a **list** to search several at once (`"state": ["ca", "ny", "tx"]`),
  which is one call instead of one per jurisdiction.
* **`federal`** is the jurisdiction for the federal corpora. A federal search
  needs only a `corpusType`, no `state`.
* Each jurisdiction row from `/us/statutes/coverage` carries a **`kind`**:
  `federal`, `state`, or `territory`. DC, Puerto Rico, Guam, the Northern Mariana
  Islands, the Virgin Islands and American Samoa are `territory`.

<Warning>
  Not every corpus type exists for every jurisdiction. A state may have its
  statutory code (`STATE`) and constitution (`STATE_CONSTITUTION`) but no
  administrative regulations (`REGULATION`) or court rules (`STATE_RULES`) yet.

  Check coverage before you scope a search. Do not assume.
</Warning>

## The two discovery endpoints

<CardGroup cols={2}>
  <Card title="GET /us/statutes/coverage" icon="table-cells">
    Which corpora exist in which jurisdiction, with document counts, freshness
    notices and retrieval status. Free, no credits.
  </Card>

  <Card title="GET /us/statutes/divisions" icon="folder-tree">
    Walk the hierarchy one level at a time: a state's codes, then its chapters,
    then its sections. Refunded on an empty level.
  </Card>
</CardGroup>

Coverage expands weekly.
Read it at request time rather than baking counts into your app.

## Reading a jurisdiction's corpora

`GET /us/statutes/coverage` returns a wrapped `{ "data": ..., "meta": ... }`
response.
Each jurisdiction in `data.jurisdictions` has a `corpora` object whose keys are
the `corpusType` tokens that actually have data, mapped to the ingested document
count.
Read those keys to know which searches you can scope.

The same response carries `data.corpusTypes`, a legend naming every token and
whether it is federal or state-scoped, so you never need a hardcoded list.

A jurisdiction that holds [state session laws](/docs/api-guide/session-laws) also carries a
`sessionLaws` block: its sessions with `status` (`complete` or `partial`), the counts served,
withheld and still open, the numbering `series` and `instrumentTypes` it holds (the values
the list and search endpoints accept) and the span of approval dates. A jurisdiction with no
session laws has no block. Session laws are not a `corpusType`.

<CodeGroup>
  ```bash cURL theme={"theme":"github-dark"}
  curl https://api.vaquill.ai/api/v1/us/statutes/coverage \
    -H "Authorization: Bearer vq_key_..."
  ```

  ```python Python theme={"theme":"github-dark"}
  import requests

  resp = requests.get(
      "https://api.vaquill.ai/api/v1/us/statutes/coverage",
      headers={"Authorization": "Bearer vq_key_..."},
  )
  data = resp.json()["data"]

  # Which corpus types does California have?
  ca = next(j for j in data["jurisdictions"] if j["code"] == "ca")
  print(ca["name"], ca["kind"], ca["sectionCount"])
  print("available corpora:", list(ca["corpora"].keys()))
  # e.g. ['STATE', 'REGULATION', 'STATE_CONSTITUTION', 'STATE_RULES']
  ```

  ```javascript JavaScript theme={"theme":"github-dark"}
  const resp = await fetch("https://api.vaquill.ai/api/v1/us/statutes/coverage", {
    headers: { Authorization: "Bearer vq_key_..." },
  });
  const { data } = await resp.json();

  // Which corpus types does California have?
  const ca = data.jurisdictions.find((j) => j.code === "ca");
  console.log(ca.name, ca.kind, ca.sectionCount);
  console.log("available corpora:", Object.keys(ca.corpora));
  // e.g. ['STATE', 'REGULATION', 'STATE_CONSTITUTION', 'STATE_RULES']
  ```
</CodeGroup>

<Note>
  A count is not an age. `data.freshness` names statute corpora that are no
  longer being refreshed. `GET /boards` carries `lastRetrievedAt` and
  `cadence` per source, so a count can be read as maintained or frozen.

  Each notice names a `(jurisdiction, corpusType)` pair, never a whole
  jurisdiction: a state can be frozen in one corpus and current in another.
</Note>

## Listing a state's codes

`state=tx` alone searches every Texas code at once.
To scope below a jurisdiction, browse its codes with `/us/statutes/divisions`
and pass one back as the `code` filter on search.

<CodeGroup>
  ```bash cURL theme={"theme":"github-dark"}
  curl -G "https://api.vaquill.ai/api/v1/us/statutes/divisions" \
    -H "Authorization: Bearer vq_key_..." \
    -d "corpusType=STATE" -d "state=tx"
  ```

  ```python Python theme={"theme":"github-dark"}
  import requests

  resp = requests.get(
      "https://api.vaquill.ai/api/v1/us/statutes/divisions",
      headers={"Authorization": "Bearer vq_key_..."},
      params={"corpusType": "STATE", "state": "tx"},
  )
  for node in resp.json()["divisions"]:
      print(node["identifier"], node["name"], node["sectionCount"])
  # tx_pe  Penal Code  ...
  ```
</CodeGroup>

Each node's `identifier` is what `code` on `POST /us/statutes/search` takes, so
browse output feeds straight back in.
Drill one level further by passing it back to `/us/statutes/divisions`
(`corpusType=STATE&state=tx&code=tx_pe` returns that code's chapters), and keep
going until `isLeaf` is true, where each node carries an `actId`.

Browse supports `USC`, `CFR`, `STATE`, `REGULATION`, `CONSTITUTION`, `STATE_CONSTITUTION` and `FEDERAL_RULES`.
Each corpus in the `/us/statutes/coverage` legend carries a `browsable` flag that says the same thing, so you never need to probe for it.
The rest are dated series or share no tree, so reach those with `/us/statutes/search`.

<Tip>
  The discovery pattern is: `/us/statutes/coverage` to see which corpora a
  jurisdiction has, `/us/statutes/divisions` to see how that jurisdiction is
  structured, then `POST /us/statutes/search` with the `corpusType`, `state` and
  `code` you confirmed.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Corpus Types" icon="layer-group" href="/docs/api-guide/concepts/corpus-types">
    The corpusType tokens and how to pair them with a state.
  </Card>

  <Card title="API Coverage" icon="map-location-dot" href="/docs/api-guide/coverage">
    The full jurisdiction matrix with current section counts.
  </Card>
</CardGroup>


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