> ## 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.
# Browse the statute hierarchy
> Walk a code top to bottom with /us/statutes/divisions: titles, chapters, parts, articles, rule sets and sections in statutory order
**What this gets you:** a table of contents for any code or title - render a browsable tree of a law in your product, the way a person would flip through it, instead of only ever surfacing single sections from search.
Search finds the section that answers a question, but it cannot enumerate a code. When you need the *structure*, titles then chapters then sections, in the order a human reads them, use `GET /us/statutes/divisions`. Each call returns the immediate children of wherever you are, so you can render a tree, build a table of contents, or crawl a whole title without paging through search.
**Endpoint used:** `GET /us/statutes/divisions`.
Browse supports `USC`, `CFR`, `STATE`, `REGULATION`, `CONSTITUTION`, `STATE_CONSTITUTION` and `FEDERAL_RULES`.
Every legend entry on `GET /us/statutes/coverage` carries a `browsable` flag that says which, so read it instead of probing.
State court rules, executive actions, the Federal Register and agency guidance are dated series or share no common tree; reach those with `POST /us/statutes/search` (see the [Quickstart](/docs/api-guide/quickstart)).
A request whose filters do not fit the corpus is rejected with `422` before anything is charged.
## How drilling works
Pass the deepest level you already know, and the response returns the level directly below it.
| You pass | You get back (`level`) |
| - | - |
| `corpusType=USC` | the USC `titles` |
| `corpusType=USC&titleNumber=42` | the `chapters` in Title 42 |
| `corpusType=USC&titleNumber=42&chapter=21` | the `sections` in Chapter 21 (leaf) |
| `corpusType=CFR&titleNumber=17` | the `parts` in Title 17 |
| `corpusType=CFR&titleNumber=17&part=240` | the `sections` in Part 240 (leaf) |
| `corpusType=STATE&state=tx` | the state's `codes` |
| `corpusType=STATE&state=tx&code=tx_pe` | the `chapters` in the Texas Penal Code |
| `corpusType=STATE&state=ny&code=ny_jud` | the `articles` in the New York Judiciary Law (New York is divided by article, not chapter) |
| `corpusType=STATE&state=ny&code=ny_jud&article=2` | the `sections` in Article 2 (leaf) |
| `corpusType=CONSTITUTION` | the `articles` and amendments of the US Constitution |
| `corpusType=CONSTITUTION&article=Amendment XIV` | the `sections` of the Fourteenth Amendment (leaf) |
| `corpusType=STATE_CONSTITUTION&state=nm` | the `articles` of the New Mexico Constitution |
| `corpusType=FEDERAL_RULES` | the rule sets (`codes`): FRCP, FRE, FRCrP, FRAP, FRBP, Supreme Court Rules |
| `corpusType=FEDERAL_RULES&code=frcp` | the Federal Rules of Civil Procedure (leaf) |
Interior nodes carry a `sectionCount` and `isLeaf: false`; drill into one by passing its `identifier` back, verbatim, as the filter its `kind` names (`title` as `titleNumber`, `chapter`, `part`, `code`, or `article`). Leaf nodes are sections with `isLeaf: true` and an `actId` you pass straight to [`/us/statutes/section/{actId}`](/docs/api-guide/concepts/section-ids). Every list comes back in statutory (natural) order: `9` before `10`, `240.9` before `240.10`.
Federal rules are published twice, by the Judicial Conference at uscourts.gov (`frcp`, `fre`, ...) and as an appendix to the U.S. Code (`uscapp_t28a_fre`, ...).
Each is its own rule set in the listing, so no rule appears twice under one heading.
On `CFR` you can pass the chapter from a citation such as "17 CFR Chapter II, Part 240": with a `part`, `chapter` is accepted and ignored, because part numbers are unique within a title.
## One level
```bash cURL theme={"theme":"github-dark"}
curl -G https://api.vaquill.ai/api/v1/us/statutes/divisions \
-H "Authorization: Bearer vq_key_..." \
--data-urlencode "corpusType=USC" \
--data-urlencode "titleNumber=42"
```
```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": "USC", "titleNumber": 42},
)
data = resp.json()
print(data["level"], "under", data["parentLabel"])
for node in data["divisions"]:
print(f' {node["identifier"]} {node["name"] or ""} ({node.get("sectionCount")} sections)')
```
```javascript JavaScript theme={"theme":"github-dark"}
const url = new URL("https://api.vaquill.ai/api/v1/us/statutes/divisions");
url.searchParams.set("corpusType", "USC");
url.searchParams.set("titleNumber", "42");
const data = await (
await fetch(url, { headers: { Authorization: "Bearer vq_key_..." } })
).json();
for (const node of data.divisions) {
console.log(node.identifier, node.name ?? "", `(${node.sectionCount} sections)`);
}
```
A trimmed response:
```json theme={"theme":"github-dark"}
{
"corpusType": "USC",
"level": "chapters",
"parentLabel": "Title 42",
"divisions": [
{ "identifier": "21", "name": "Civil Rights", "kind": "chapter", "isLeaf": false, "sectionCount": 62 },
{ "identifier": "21A", "name": "Privacy Protection", "kind": "chapter", "isLeaf": false, "sectionCount": 9 }
],
"count": 2
}
```
## Walk a whole title
Drill from a title to its chapters, then each chapter to its sections. Leaf nodes carry the `actId` you use to fetch metadata or full text.
```python Python theme={"theme":"github-dark"}
import requests
BASE = "https://api.vaquill.ai/api/v1/us"
HEADERS = {"Authorization": "Bearer vq_key_..."}
def divisions(**params) -> dict:
resp = requests.get(f"{BASE}/statutes/divisions", headers=HEADERS, params=params)
resp.raise_for_status()
return resp.json()
def walk_title(corpus_type: str, title_number: int) -> None:
chapters = divisions(corpusType=corpus_type, titleNumber=title_number)
for ch in chapters["divisions"]:
print(f'Chapter {ch["identifier"]}: {ch["name"] or ""}')
sections = divisions(
corpusType=corpus_type, titleNumber=title_number, chapter=ch["identifier"]
)
for sec in sections["divisions"]:
# sec["actId"] -> feed into POST /us/statutes/sections (see below)
print(f' ยง {sec["identifier"]} {sec["name"] or ""} [{sec["actId"]}]')
walk_title("USC", 42)
```
A leaf listing is bounded to keep one call fast, so a large container comes back in more than one page.
Check `truncated` on every section listing. When it is `true`, the response also carries `nextCursor`: pass it back as `cursor` and keep going until it is `null`.
```python theme={"theme":"github-dark"}
def all_sections(**scope) -> list[dict]:
out, cursor = [], None
while True:
page = divisions(**scope, **({"cursor": cursor} if cursor else {}))
out += page["divisions"]
cursor = page.get("nextCursor")
if not cursor:
return out
```
Do not reach for `POST /us/statutes/search` to finish an enumeration. Search is capped at 120 results for any one query, so it cannot complete a container that browse could not.
Rows are sorted into statutory order **within** each response, and pages are walked in storage order, so concatenating pages does not give you one globally sorted list. The union of every page is the complete container. Sort it yourself once you hold it all.
## Export a container with its text
Enumeration gives you identifiers. To turn a chapter into text, batch those `actId` values through `POST /us/statutes/sections` with `includeBody`, 50 at a time.
```python theme={"theme":"github-dark"}
def export_container(**scope) -> list[dict]:
ids = [s["actId"] for s in all_sections(**scope) if s.get("actId")]
out = []
for i in range(0, len(ids), 50):
resp = requests.post(
f"{BASE}/statutes/sections",
headers=HEADERS,
json={"actIds": ids[i : i + 50], "includeBody": True},
)
resp.raise_for_status()
out += resp.json()["sections"]
return out
```
Two calls per 50 sections, and no per-section round trip. `includeBody` bills the ordinary body price for each row that returns text; rows whose text cannot be resolved come back with `body: null` and are not charged for it, so read `creditsConsumed` on each response instead of computing it.
Text is the expensive half of any export. If you are filtering, run the filter on metadata first (omit `includeBody`) and fetch bodies only for what survives.
Size the container before you walk it. `POST /us/statutes/count` takes the same scoping filters, runs no ranking, and returns an exact section count for one credit, which tells you what an export will cost before you start it.
## Search within a container
Browse and search meet at the `parent` object.
A search result from any browsable corpus carries a `parent`: the ready-made query that lists its siblings.
Every key it carries (`titleNumber`, `chapter`, `part`, `code`, `article`) is also a `POST /us/statutes/search` filter, so you can take any hit and run a search confined to its chapter, part, article or rule set, without building the scope yourself.
| A hit from | carries a `parent` like |
| - | - |
| `USC` | `{"corpusType": "USC", "titleNumber": 42, "chapter": "21"}` |
| `CFR` | `{"corpusType": "CFR", "titleNumber": 17, "part": "240"}` |
| `STATE` / `REGULATION` | `{"corpusType": "STATE", "state": "tx", "code": "tx_pe", "chapter": "31"}` |
| a New York code | `{"corpusType": "STATE", "state": "ny", "code": "ny_jud", "article": "2"}` |
| `CONSTITUTION` | `{"corpusType": "CONSTITUTION", "article": "Amendment XIV"}` |
| `STATE_CONSTITUTION` | `{"corpusType": "STATE_CONSTITUTION", "state": "nm", "article": "Article IV"}` |
| `FEDERAL_RULES` | `{"corpusType": "FEDERAL_RULES", "code": "frcp"}` |
The same object replays against `GET /us/statutes/divisions` unchanged, so one hit gives you both the listing of its container and a search within it.
```python Python theme={"theme":"github-dark"}
import requests
BASE = "https://api.vaquill.ai/api/v1/us"
HEADERS = {"Authorization": "Bearer vq_key_..."}
def search(body: dict) -> dict:
resp = requests.post(f"{BASE}/statutes/search", headers=HEADERS, json=body)
resp.raise_for_status()
return resp.json()
# 1. Find one on-point section.
hit = search({"query": "insider trading", "corpusType": "CFR", "limit": 1})["results"][0]
# 2. Reuse its parent to search only within that part (17 C.F.R. Part 240).
neighbors = search({"query": "manipulative devices", "limit": 10, **hit["parent"]})
for r in neighbors["results"]:
print(r["actId"], r["citation"])
```
`chapter` and `part` accept a single value or a list, and must be paired with `titleNumber` (USC/CFR) or `code` (state), which `parent` always includes. A chapter number alone repeats across every title, so an unpaired `chapter`/`part` is rejected with `422`.
`article` follows the same logic, because article labels repeat too:
* It needs a `corpusType` from one family: `CONSTITUTION` / `STATE_CONSTITUTION`, where it is the article label browse lists (`Amendment XIV`), or `STATE` / `REGULATION`, where it is the article of a code divided by article instead of chapter (New York's `2-A`).
* `STATE_CONSTITUTION` also needs `state`, since most state constitutions have an `Article IV`.
* On `STATE` / `REGULATION` it needs the `code` it belongs to, and it cannot be combined with `chapter`.
Pass the `identifier` exactly as the listing returned it; a case slip such as `amendment xiv` also matches.
A federal rule set is a `code` under `corpusType=FEDERAL_RULES`: `frcp`, `fre`, `frcpsuppadm`, or an appendix copy such as `uscapp_t28a_fre`.
Without that `corpusType`, `frcp` cannot be told apart from a state code missing its state, so it is refused.
`code=frcp` is the Federal Rules of Civil Procedure alone; `source=frcp` also covers the FRCP supplemental rules.
Each of these shape errors is a `422` decided before anything is charged.
## Related
The `actId` you get from a leaf node, and how to fetch its metadata and text.
The corpora you can browse and how to scope with `corpusType` and `state`.
Which jurisdictions exist, and what the two-letter `state` codes mean.
Go straight to a section from a Bluebook citation instead of walking to it.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.