--- title: "Browse the statutory hierarchy" method: GET path: "/api/v1/us/statutes/divisions" tags: ["US Statutes"] --- # Browse the statutory hierarchy `GET /api/v1/us/statutes/divisions` ## Request - Base URL: `https://api.vaquill.ai` - URL: `https://api.vaquill.ai/api/v1/us/statutes/divisions` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Walk the statutory tree one level at a time, in statutory order. Each call returns the immediate children of wherever you are. Following every node down, and every `nextCursor` across, reaches every section the corpus holds for that scope, so a code can be enumerated without searching. **Cost**: 1 credit. A request whose filters do not fit the corpus is rejected before anything is charged. So is a filter naming a container that does not exist, a browse that returns no rows, and a failure on our side: the credit is taken only once a level with rows is ready to return, so exploring the hierarchy never costs you anything for a level that turns out to be empty. Pass the deepest level you already know; the response returns the level below it: - `corpusType=USC` -> the titles - `corpusType=USC&titleNumber=42` -> the chapters in Title 42 - `corpusType=USC&titleNumber=18` -> the parts of Title 18 (a title whose chapters sit in parts, subtitles or divisions lists those first) - `corpusType=USC&titleNumber=18&part=I` -> the chapters in Part I of Title 18 - `corpusType=USC&titleNumber=8&chapter=12` -> the subchapters of Chapter 12 (a chapter with no subchapters lists its sections) - `corpusType=USC&titleNumber=8&chapter=12&subchapter=II` -> the parts of Subchapter II (Parts I to IX) - `corpusType=USC&titleNumber=8&chapter=12&subchapter=II&part=I` -> the sections in Part I (leaf) - `corpusType=CFR&titleNumber=17` -> the chapters of Title 17 (a title with subtitles, such as 29, lists them first; a title whose parts sit in no chapter lists its parts) - `corpusType=CFR&titleNumber=29&subtitle=B` -> the chapters of Subtitle B of Title 29 (Subtitle A lists its parts directly) - `corpusType=CFR&titleNumber=29&chapter=XIV` -> the parts of Chapter XIV of Title 29 - `corpusType=CFR&titleNumber=17&part=240` -> the subparts and subject groups of Part 240 (a part with neither lists its sections) - `corpusType=CFR&titleNumber=17&part=240&subpart=A` -> the subject groups of Subpart A - `corpusType=CFR&titleNumber=17&part=240&subpart=A&subjectGroup=Rules of General Application` -> the sections in that subject group (leaf) - `corpusType=CFR&titleNumber=17&part=240&subjectGroup=ECFRf2ef38fa463cdfa` -> the same sections (leaf), by the group's eCFR id (a subject-group node's `subjectGroupId`) - `corpusType=STATE&state=tx` -> the state's codes - `corpusType=STATE&state=tx&code=tx_pe` -> the titles of the Texas Penal Code - `corpusType=STATE&state=tx&code=tx_pe&title=5` -> the chapters in Title 5 of the Texas Penal Code - `corpusType=STATE&state=tx&code=tx_gv&title=5&subtitle=B` -> the chapters in Subtitle B of Title 5 of the Texas Government Code - `corpusType=STATE&state=ca&code=ca_pen` -> the parts of the California Penal Code - `corpusType=STATE&state=ca&code=ca_edc&title=1&division=1&part=11&chapter=2` -> the articles of the Education Code's Chapter 2 in Part 11 (one of its many chapters numbered 2) - `corpusType=STATE&state=ny&code=ny_jud&article=2` -> the sections in a New York article (leaf) - `corpusType=STATE&state=il&code=il_225` -> the acts in 225 ILCS, a code that is a single chapter - `corpusType=STATE&state=de&code=de_6&article=2` -> the parts of UCC Article 2 in Delaware Title 6, which sits outside any chapter - `corpusType=STATE&state=de&code=de_6&article=2&part=2` -> the sections in Part 2 of UCC Article 2 (leaf) - `corpusType=REGULATION&state=ny&code=ny_10&chapter=I` -> the parts in Chapter I of 10 NYCRR - `corpusType=STATE_RULES&state=tx` -> the state's court rule sets (Rules of Civil Procedure, each county's local rules, ...) - `corpusType=STATE_RULES&state=tx&code=HARRIS` -> the rule sets inside Harris County's local rules, as `kind: chapter` - `corpusType=STATE_RULES&state=wi&code=SCR61` -> the rules of Wisconsin SCR Chapter 61, which records no level inside it (leaf) - `corpusType=CONSTITUTION` -> the articles and amendments of the US Constitution - `corpusType=CONSTITUTION&article=Article III` -> the sections of Article III (leaf) - `corpusType=STATE_CONSTITUTION&state=nm` -> the articles of the New Mexico Constitution - `corpusType=FEDERAL_RULES` -> the rule sets (FRCP, FRE, FRCrP, ...) - `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 as the filter its `kind` names (`title` -> `titleNumber` on the U.S. Code and CFR and `title` inside a state code, `chapter`, `subchapter`, `part`, `subpart`, `subtitle`, `division`, `subdivision`, `subjectGroup`, `code`, `article`, `act`, and on state regulations `umbrella`, `agency`, `program`), keeping the filters you already passed. One listing can mix kinds: a state code lists its chapters, then the containers and loose sections outside them, a U.S. Code chapter lists any section outside a subchapter beside its subchapters, and a subchapter any section outside a part beside its parts. Read `kind` on each node rather than assuming it from `level`. Leaf nodes are sections and carry an `actId` for `/us/statutes/section/{actId}`. A U.S. Code level does not sit at one fixed depth: Title 18's parts are above its chapters, while the parts of 8 U.S.C. ch. 12 are inside its subchapters. Pass each level a listing returned, in any order; a number that fits more than one place (`part=I` in a chapter whose subchapters each have a Part I) is refused with the containers to add. A CFR subject group has no stable number, so its `identifier` is its heading, matched case-insensitively. A state level is listed only where the corpus records it, so which levels a code has is read from its own sections, never assumed: a code whose sections record a title, subtitle or division above their chapters (Texas titles and subtitles, California's divisions, parts and titles, Maryland's titles and subtitles) lists that level first, and each listing below it names the next level those sections record. Some codes record no level below the code (Colorado titles list their articles; Louisiana's Civil Code lists its sections directly), and `note` says so. A number that repeats inside one code (a California chapter `2` sits in dozens of parts) names one container only together with the levels above it; passed alone, it lists the sections of every container that carries it, flat, with a `note`. A state subtitle or division is never matched across titles: pass the `title` it sits in. State regulations that print the agency above their chapters (Maine umbrellas and agencies, Wyoming programs, Virginia agencies) list it as `kind: agency`, `program` or `umbrella`, and a chapter number repeated under two of them names one container only together with its agency. Court rules (`STATE_RULES`) list a state's rule sets first, as `kind: code`. Inside a rule set, each container its rules' records name (a chapter, part, division, district or heading) is listed with the filter that drills into it as `kind`: `chapter` for the first level, then `part`, `subchapter`, `article` and `act`, whatever the publisher calls the level, with the publisher's heading as `name`. Keep `code` and every filter you already passed. A listing larger than one response pages: `truncated` is true and `nextCursor` continues it. Pass the cursor back with the same filters until it comes back null. If `note` says a listing could not hold everything, it also says where the rest is. Browse supports `USC`, `CFR`, `STATE`, `REGULATION`, `STATE_RULES`, `CONSTITUTION`, `STATE_CONSTITUTION` and `FEDERAL_RULES`, which is also what `browsable` says on each `GET /us/statutes/coverage` legend entry. The rest are dated series or share no tree, so use `/us/statutes/search` for those. 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 here, so neither is listed twice under one heading. ## Query parameters - `corpusType` 'USC' | 'CFR' | 'STATE' | 'REGULATION' | 'STATE_RULES' | 'CONSTITUTION' | 'STATE_CONSTITUTION' | 'FEDERAL_RULES', required: Corpus to browse. Case-insensitive. The browsable subset of the `corpusType` tokens on `/us/statutes/coverage`. - `state` 'al' | 'ak' | 'as' | 'az' | 'ar' | 'ca' | 'co' | 'ct' | 'de' | 'dc' | 'fl' | 'ga' | 'gu' | 'hi' | 'id' | 'il' | 'in' | 'ia' | 'ks' | 'ky' | 'la' | 'me' | 'md' | 'ma' | 'mi' | 'mn' | 'ms' | 'mo' | 'mt' | 'ne' | 'nv' | 'nh' | 'nj' | 'nm' | 'ny' | 'nc' | 'nd' | 'mp' | 'oh' | 'ok' | 'or' | 'pa' | 'pr' | 'ri' | 'sc' | 'sd' | 'tn' | 'tx' | 'ut' | 'vt' | 'vi' | 'va' | 'wa' | 'wv' | 'wi' | 'wy', nullable: 2-letter jurisdiction code, required for the state-scoped corpora (STATE, REGULATION, STATE_RULES, STATE_CONSTITUTION). Case-insensitive. - `titleNumber` union: USC/CFR title number to drill into. On the U.S. Code, `5a` and `18a` name the Appendix to Title 5 and Title 18 (a title list returns them as their own rows). - integer - '5a' | '18a' - `code` string, nullable: Code to drill into: a state code such as `tx_pe` (list them with `corpusType=STATE&state=`), a federal rule set such as `frcp` (list them with `corpusType=FEDERAL_RULES`), or a state court rule set such as `HARRIS` (list them with `corpusType=STATE_RULES&state=`). - `chapter` string, nullable: Chapter identifier to drill into (USC, CFR and state codes), or the first level inside a court rule set (a node with `kind: chapter`; needs `code`). On CFR it lists the chapter's parts (needs `titleNumber`); accepted alongside `part`, where it is not needed: part numbers are unique within a title. - `part` string, nullable: Part to drill into: a CFR part, a U.S. Code part (Title 18 Part I, or Parts I to IX of 8 U.S.C. ch. 12 subch. II; needs `titleNumber`), or a part of a state code or court rule set wherever a listing returned one with `kind: part` (NYCRR, Mississippi and Colorado regulations and statutes, Pennsylvania court rules). On a state code or rule set it needs `code`. - `article` string, nullable: Article to drill into: a constitution's article or amendment (`Article III`, `Amendment XIV`), or an article of a state code wherever a listing returned one with `kind: article` (New York's codes, or the UCC articles outside any chapter in Delaware Title 6), or of a court rule set (`kind: article`, Pennsylvania's Rules of Evidence). On a state code it can be combined with `chapter` to narrow to one article within that chapter. Pass the `identifier` exactly as the listing returned it. - `excludeRepealed` boolean: Leave out sections whose status is affirmatively dead (repealed, superseded, renumbered and similar). A section carrying no recorded status is KEPT: a missing status is not evidence of repeal. Same vocabulary as the filter of this name on `POST /us/statutes/search`. - `actStatus` 'abolished' | 'deleted' | 'expired' | 'in_force' | 'inactive' | 'non_precedential' | 'not_funded' | 'not_yet_effective' | 'omitted' | 'proposed' | 'recodified' | 'recompiled' | 'rejected' | 'relocated' | 'removed' | 'renumbered' | 'repealed' | 'rescinded' | 'reserved' | 'revoked' | 'superseded' | 'terminated' | 'transferred' | 'unconstitutional' | 'vacant' | 'vacated' | 'vetoed' | 'withdrawn', nullable: List only sections carrying this status, e.g. `repealed`. The inverse of `excludeRepealed`, and useful for auditing what a container holds that is no longer operative. - `subchapter` string, nullable: The subchapter to list, as a listing returned it (`kind: subchapter`): a U.S. Code subchapter (needs `titleNumber` and `chapter`), a CFR subchapter a listing returned directly under a subtitle (45 CFR Subtitle A; needs `titleNumber`), or a state or court-rule subchapter (needs `code`). Case-insensitive. - `act` string, nullable: The act to list, as a listing returned it (`kind: act`): an Illinois act inside an ILCS chapter or a Pennsylvania unconsolidated act (needs `code`), or an Act inside a U.S. Code title's Appendix, such as `Pub. L. 96-456` (needs `titleNumber` `5a` or `18a`). - `title` string, nullable: State codes and regulations only: the title inside a code to list, as a listing returned it (`kind: title`), such as Title 5 of the Texas Penal Code. Needs `code`. A U.S. Code or CFR title is `titleNumber`. - `subtitle` string, nullable: The subtitle to list, as a listing returned it (`kind: subtitle`): a U.S. Code or CFR subtitle such as Subtitle A of Title 26 or Subtitle B of Title 29 CFR (needs `titleNumber`), or a subtitle of a state code such as Subtitle B of Title 5 of the Texas Government Code (needs `code` and the `title` it sits in). - `division` string, nullable: The division to list (`kind: division`): a U.S. Code division, as in Title 54 or 42 U.S.C. ch. 157 (needs `titleNumber`), or a division of a state code or regulation code, as in California's codes (needs `code`, and the levels above it that the listing returned). - `subdivision` string, nullable: U.S. Code only: the subdivision to list (`kind: subdivision`, Title 54). Needs the `division` it belongs to. - `subpart` string, nullable: The subpart to list (`kind: subpart`): a U.S. Code subpart (needs the `part` it belongs to and `titleNumber`), a CFR subpart (needs `titleNumber` and `part`), or a subpart of a state regulation code such as Louisiana's or Mississippi's (needs `code`, and the `part` it sits in). Case-insensitive. - `umbrella` string, nullable: State regulations only: the umbrella to list (`kind: umbrella`), as a listing returned it. Maine groups its agencies under a department umbrella (`10` is the Department of Health and Human Services). Needs `code`. - `agency` string, nullable: State regulations only: the agency to list (`kind: agency`), as a listing returned it, such as Maine agency `144` or a Virginia agency inside a title. A chapter number repeats under different agencies, so name the agency to open the right chapter. Needs `code`. - `program` string, nullable: State regulations only: the program to list (`kind: program`), as a listing returned it. Wyoming prints a program between an agency and its chapters, and chapter `1` repeats under every program. Needs `code`. - `subjectGroup` string, nullable: CFR only: the subject group to list (`kind: subjectGroup`), passed back as the heading the listing returned, or as its eCFR id (`ECFR` and 15 hex digits, the node's `subjectGroupId`), which lists the same sections and needs no `subpart`. Needs `titleNumber` and `part`, and the `subpart` when a heading names a group inside one. Case-insensitive. - `cursor` string, nullable: Resume token from a previous response's `nextCursor`, passed back with the same filters. Omit it to start at the beginning of the listing. ## Headers - `Idempotency-Key` string, nullable: Optional. 16 to 255 visible ASCII characters (a UUIDv4 is ideal). A retry with the same key and the same request replays the original 2xx response for 24 hours without charging again. The same key with a different request is rejected. Scope is the API key, method, path and body. The stored response body is a query-derived cache controlled by the account's data retention setting cacheQueryDerivedData: when it is false the body is never stored and a retry answers 409 idempotency_replay_unavailable, without charging again. ## Response `200` The child divisions at the requested level. - UsStatutesDivisionsResponse: Response for `GET /us/statutes/divisions`. - `corpusType` string, required: The corpus being walked, echoed back from the request. - `state` string, nullable: The jurisdiction, for state-scoped corpora. - `level` string, required: Kind of children returned: `titles`, `chapters`, `subchapters`, `parts`, `subparts`, `subtitles`, `divisions`, `subdivisions`, `subjectGroups`, `codes`, `articles`, `acts`, or `sections`. A listing can mix kinds; this names the main one, and `kind` on each node is authoritative. - `parentLabel` string, nullable: Human label for the container these divisions sit under. - `divisions` UsDivisionNode[]: The child divisions, in statutory (natural) order. - `identifier` string, required: The division's identifier within its parent, e.g. `42` (title), `21` (chapter), `240` (part), `tx_pe` (state code), `frcp` (federal rule set), `SCR61` (state court rule set), `Article III` (article), or `1983` (section). Pass it back verbatim. - `name` string, nullable: Human-readable name of the division, when the source provides one. A heading the publisher prints in capitals is served in title case. - `label` string, nullable: The citation form of a state `code` (`8 Del. C.`, `Tex. Penal Code`). `name` carries the publisher's heading for the code (`Corporations`) when its sections hold one, and the same text as `label` when they do not. Null on every other kind. - `kind` string, required: Division kind, which is also the filter to drill into it with: `title` (as `titleNumber` on the U.S. Code and CFR, as `title` inside a state code), `chapter`, `subchapter`, `part`, `subpart`, `subtitle` (also a CFR subtitle), `division`, `subdivision`, `subjectGroup` (a CFR subject group, whose identifier is its heading and whose eCFR id is `subjectGroupId`), `code`, `article`, `act`, or `section` (a leaf; fetch it by `actId`). - `isLeaf` boolean, required: True for sections (terminal nodes); false for interior divisions. - `actId` string, nullable: Section identifier, present only on leaf sections. Pass it to `/us/statutes/section/{actId}`. - `sectionCount` integer, nullable: Distinct sections under an interior division: the number of distinct act_ids, equal to what drilling into the division lists. A stacked prior version that has its own act_id counts separately; two points of one act_id count once. Null on leaf sections. - `status` string, nullable: A section leaf's stored status (`in_force`, `repealed`, `superseded`, ...) when the listing carries it, so a client can mark repealed law without fetching each section. Null on interior divisions. - `subjectGroupId` string, nullable: CFR subject groups only (`kind: subjectGroup`): the eCFR identifier of the group (`ECFR` and 15 hex digits), so a path saved from eCFR maps to this listing. Pass it back as `subjectGroup`, with `titleNumber` and `part`, and it lists the same sections as the heading does. Null when the group has no single id: the same heading is two sibling groups in one part, or the id table is older than the heading. - `count` integer: Number of divisions returned. - `nextCursor` string, nullable: Opaque token to resume this listing. Present only when `truncated` is true. Pass it back as `cursor` to get the next batch of sections in the same container, and keep going until it comes back null. Treat it as opaque: it encodes a storage position, and building one by hand will not work. Ordering. A cursor starting `o~` continues one listing in a single statutory order, so concatenating its pages gives the sorted whole. A cursor starting `s~` walks a container too large to sort in one pass: each page is in statutory order, pages follow storage order, and the union of every page is the complete container, so sort it yourself once you hold it all. - `truncated` boolean: True when this container held more sections than one call can walk, so `divisions` is a PREFIX of its contents rather than all of them. Check it before treating a listing as complete: the level that returns sections is bounded, and a container past that bound previously returned a short list that looked whole. When it is true, narrow the scope (drill into a chapter or part rather than a whole code), or page through it with `nextCursor`. - `note` string, nullable: Why the result is empty, when it is. Absent on a normal result. An empty `divisions` with a note is an answer; without one it would be ambiguous between a bad identifier and a level this corpus does not store. - `processingTimeMs` number: Server-side time for this request in milliseconds, excluding network transit. Useful for spotting a slow query; not billed on. - `creditsConsumed` number: Credits actually charged for this call. Read it rather than assuming the list price: failed and refunded work bills 0, and batch endpoints charge per item returned, so a partial result costs less than a full one. ## Other responses - `401`: Invalid or missing API key. - `402`: Insufficient credits. - `409`: Idempotency conflict. `idempotency_in_progress`: the original request with this key is still running (retry after `Retry-After`). `idempotency_replay_unavailable`: it completed but its response was too large to replay; nothing is charged again, so check the credit balance instead of retrying. - `422`: Filters do not fit the corpus shape. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different request. - `429`: Rate limit exceeded. --- [API](https://skmtc.dev/vaquill/apis/vaquill-developer-api.md) - [All operations](https://skmtc.dev/vaquill/apis/vaquill-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vaquill/apis/vaquill-developer-api/revisions/fbac9b87775e?raw)