--- title: "Search US statutes, constitutions, court rules, and executive actions" method: POST path: "/api/v1/us/statutes/search" tags: ["US Statutes"] --- # Search US statutes, constitutions, court rules, and executive actions `POST /api/v1/us/statutes/search` ## Request - Base URL: `https://api.vaquill.ai` - URL: `https://api.vaquill.ai/api/v1/us/statutes/search` - 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) Search US federal and state law and get back the most relevant sections, with citations and links to the official source documents. State session laws (acts as enacted) are at `/us/session-laws`. Scope a search with `corpusType` (the field lists every token). `GET /us/statutes/coverage` shows what is held per jurisdiction and corpus; the [Coverage page](https://www.vaquill.ai/docs/api-guide/coverage) explains it. Narrow further with `state`, `code`, `article`, `titleNumber`, `chapter` and `part`, and for `AGENCY_GUIDANCE` with `source`. Pass `corpusType` whenever you know it: an unscoped query can surface keyword matches from unrelated corpora. **Cost**: 4 credits per call. Refunded on a failure, on a page served with `rankingDegraded: true` (the relevance model was down), and on a filtered search that matches no section (a `notes` entry names the filters). A search that ran in full and found nothing on point (`noGoodMatch: true`) is charged, because the work was done; its rows are the nearest sections, not matches, so check `noGoodMatch` and `matchQuality` before using them. A 422 is never charged. `includeBody: true` returns each hit's full text inline on `body`, at the ordinary 6-credit body price per row that returns text. If your balance cannot cover every body, the rows it can cover are served and charged in rank order and the rest carry `bodyNote: insufficient_credits`. Read `creditsConsumed`. `includePinpoint: true` names the subsection each hit matched, in `pinpoints` keyed by `actId`, at no extra cost. Both switches are described on their fields. `matchType` is `any` (default, hybrid semantic and keyword), `all`, `phrase` or `boolean` (a terms-and-connectors expression; the operators are listed on that field). Pass a citation as the `query` (e.g. `42 U.S.C. § 1983`) and it resolves to rank 1 at `relevanceScore: 1.0`; if you already know the citation, `GET /us/statutes/resolve` returns the same section for less. **Pagination**: `limit` is at most 50. With `matchType: "any"`, `offset` is at most 70 and ranked results come from a bounded pool, so about 60 to 90 results are reachable and `hasMore` turns false at the end of it. With `boolean`, `all` or `phrase`, `offset` goes up to 10,000; follow `nextOffset` until `hasMore` is false. A later page can hold fewer rows than `limit`, because candidates outside your filters or failing full-text verification are left out. Every page of one query slices one ranking, so results never repeat or go missing across pages. `count` is the size of the current page, not a corpus-wide total (`total` is a deprecated alias for `count`). **Boolean results**: every result satisfies the expression, judged over the section's full text. `totalMatches` says how many sections match (`totalMatchesExact: false` marks an upper bound). The first `relevanceRankedCount` results (at most 120) are ordered by relevance and later pages continue in keyword (BM25) order. `parsedQuery` shows how the expression was read. A malformed expression is a 422 that names the problem and its position. A query written in Boolean syntax but sent with `matchType: "any"` runs as natural language and says so in `queryHint`. `POST /us/statutes/count` returns the same total without the results. `relevanceScore` ranks results within one response; do not compare it across queries. Take a returned `actId` to `/us/statutes/section/{actId}` for metadata or `/us/statutes/section/{actId}/body` for the full text, or POST up to 50 ids to `/us/statutes/sections` instead of looping. **Bounded rows.** A heavily amended section (26 U.S.C. 1) carries hundreds of references and a credit line of tens of thousands of characters. Each row keeps the first 50 items of every long list and the first 4,000 characters of `history` and `committeeNote`. A row that was cut carries `responseBounds` (`truncated`, and per field the `total`, what was `returned` and `nextOffset`); a row that was not cut omits it. The whole record is one call away: `GET /us/statutes/section/{actId}?full=true`. ## Headers - `Idempotency-Key` string, nullable: Optional. 16 to 255 visible ASCII characters (a UUIDv4 works). Repeating the same request with the same key replays the original 2xx response for 24 hours without charging again. The same key on a different request is rejected. With the account's `cacheQueryDerivedData` retention setting off, no body is stored and a retry answers 409 `idempotency_replay_unavailable`, still without a second charge. ## Request body - StatuteSearchRequest - `query` string, required: Search query in natural language. - `corpusType` union: Restrict to one corpus, or to several by passing a list (`"corpusType": ["USC", "CFR"]`). One of: `USC` (United States Code), `CFR` (Code of Federal Regulations), `STATE` (state statutory codes; call `/us/statutes/coverage` for the list of ingested jurisdictions), `CONSTITUTION` (U.S. Constitution), `FEDERAL_RULES` (FRCP / FRCrP / FRE / FRAP / FRBP), `STATE_CONSTITUTION` (state constitutions; call `/us/statutes/coverage` for the current jurisdiction list), `STATE_RULES` (state court rules; see `/us/statutes/coverage`), `EXECUTIVE_ACTION` (Federal Register Presidential Documents), `REGULATION` (state administrative regulations; pair with `state`), `FEDERAL_REGISTER` (Federal Register agency rules, final and proposed), `AGENCY_GUIDANCE` (sub-regulatory federal agency guidance, 53 named sources spanning the tax, banking, securities, labor, immigration, health-privacy, export-control, intellectual-property, antitrust, energy and communications agencies; each is independently filterable with `source`, which lists them all), `STATE_AGENCY_GUIDANCE` (state-issued regulatory guidance, currently state Department of Insurance bulletins and circular letters; pair with `state`, and see `/us/statutes/coverage`), `SENTENCING_GUIDELINES` (US Sentencing Guidelines Manual), `US_TAX_TREATY` (US income tax treaties and protocols), `US_TREATY` (treaty and international agreement text from the Statutes at Large, U.S.T., T.I.A.S. and Bevans, plus the Senate ratification record), `SESSION_LAW` (US Statutes at Large: federal public and private laws AS ENACTED, 1789 to date. This is the source the US Code is compiled from, so a section's `publicLawCites` resolve here to the enacting text; call `/us/statutes/coverage` for the live section count), `FEDERAL_LOCAL_RULES` (Federal local court rules), `FEDERAL_REGISTER_NOTICE` (Federal Register notices that act on a rulemaking), `STATE_AG_OPINION` (Formal written opinions of a state Attorney General, construing that state's own statutes, constitution and...), `STATE_REGISTER` (State administrative register NOTICES), `STATUTE_COMPILATION` (Statute compilations), `AGENCY_ADJUDICATION` (Federal administrative adjudications and executive-branch legal opinions, one filterable `source` per body), `CFR_ANNUAL` (GPO's PUBLISHED ANNUAL EDITIONS of the Code of Federal Regulations, 1996 to date), `USC_ANNUAL` (GPO's PUBLISHED ANNUAL EDITION of the United States Code, retired here when the live Code cut over to OLRC...), `FEDERAL_BILL` (Congressional BILLS and resolutions of the 119th Congress, as printed by GPO), `FEDERAL_RULES_ANNUAL` (PAST TEXTS of the national Federal Rules of Civil Procedure, Criminal Procedure, Evidence, Appellate...), `FEDERAL_RULES_PROPOSED` (PENDING AMENDMENTS to the national Federal Rules, one document per rule per Rules Enabling Act cycle...). Omit to search across all corpora. The `enum` on this field is the complete token list, and `/us/statutes/coverage` serves a one-line description of each in its legend. - 'USC' | 'CFR' | 'STATE' | 'CONSTITUTION' | 'FEDERAL_RULES' | 'FEDERAL_LOCAL_RULES' | 'STATE_CONSTITUTION' | 'STATE_RULES' | 'EXECUTIVE_ACTION' | 'REGULATION' | 'FEDERAL_REGISTER' | 'FEDERAL_REGISTER_NOTICE' | 'AGENCY_GUIDANCE' | 'SENTENCING_GUIDELINES' | 'US_TAX_TREATY' | 'US_TREATY' | 'STATE_AGENCY_GUIDANCE' | 'STATE_AG_OPINION' | 'STATE_REGISTER' | 'SESSION_LAW' | 'STATUTE_COMPILATION' | 'AGENCY_ADJUDICATION' | 'CFR_ANNUAL' | 'USC_ANNUAL' | 'FEDERAL_BILL' | 'FEDERAL_RULES_ANNUAL' | 'FEDERAL_RULES_PROPOSED': A public `corpusType` token. - CorpusType[] - `state` union: Jurisdiction filter. A 2-letter code for one of the 56 supported US jurisdictions (50 states + DC + PR, GU, VI, AS, MP), or `federal` to scope to USC / CFR / Constitution / federal rules. Pass a LIST to search several at once (`"state": ["ca", "ny", "tx"]`), which is one call instead of one per jurisdiction. Case-insensitive: `ca` and `CA` both work. An unrecognized value is rejected with 422 rather than silently matching nothing. Omit to search every jurisdiction. - 'federal' | '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' - string[] - `code` union: Restrict to specific state statutory codes, e.g. `tx_pe` for the Texas Penal Code. Values are the `identifier`s returned by `GET /us/statutes/divisions?corpusType=STATE&state=XX`, so the browse output can be fed straight back in. Pass a list to search several codes, across states if you like (`["tx_pe", "ca_pen"]`). This is the only way to scope below a whole jurisdiction: `state=tx` alone searches every Texas code at once. With `corpusType=FEDERAL_RULES`, a value can instead be a federal rule set as `GET /us/statutes/divisions?corpusType=FEDERAL_RULES` lists it: `frcp`, `fre`, `frcpsuppadm`, or an appendix copy such as `uscapp_t28a_fre`. Without that corpusType a bare `frcp` is refused, because it cannot be told apart from a state code missing its state. - string - string[] - `article` union: Scope a search to one or more articles. On `CONSTITUTION` and `STATE_CONSTITUTION` this is the article label as `GET /us/statutes/divisions` lists it (`Amendment XIV`, `Article IV`, `Preamble`). On `STATE` / `REGULATION` it is the article of a code divided by article instead of chapter, such as New York (`2-A` in `ny_jud`). This is the search side of `parent.article`: pass a hit's `parent` straight back to search within its article. Pass the `identifier` exactly as the listing returned it; a case slip such as `amendment xiv` also matches. Article labels repeat, so `article` needs a `corpusType` from one of those two families, `STATE_CONSTITUTION` also needs `state`, and `STATE` / `REGULATION` need the `code`. A request missing one is refused with 422 before anything is charged. String or list. - string - string[] - `yearFrom` integer, nullable: Only return sections dated in or after this year. Combine with `yearTo` for a window. A section matches on the first of three years it carries: the most recent amendment the publisher credits in its own history note; else its effective year, for a section adopted once and never amended; else, for corpora dated by publication rather than amendment (Federal Register proposed rules, agency guidance, adjudications, the treaty record), the document's own publication or issue year. Every one of those tracks the LAW or the document, never when we last rebuilt the corpus. A section carrying none of the three is excluded once either bound is set, so an unbounded search returns strictly more. - `yearTo` integer, nullable: Only return sections dated in or before this year, on the same three years `yearFrom` describes. Note it filters the LAST such date, so a section amended in 2025 is excluded by `yearTo=2024` even though it existed in 2024. This is a currency filter, not point-in-time retrieval: the corpus holds one current text per citation. - `excludeRepealed` boolean: Drop sections whose own status says they are no longer operative: repealed, renumbered, transferred, recodified, rescinded, revoked, expired, superseded, omitted, reserved, and the rest of the dead and not-operative vocabulary (the full set is the one behind each result's `goodLawStatus`). This removes what we KNOW is dead. It does not promise the remainder is good law. A section survives this filter when its status is `in_force` OR when we hold no trustworthy repeal signal for its jurisdiction, and those two are not the same thing. Read `goodLawStatus` on each surviving result to tell them apart: `good_law` is checked, `unknown` is unchecked. Filtering on the status we store and reporting the verdict we derive are deliberately separate, because only the first is indexable. The United States Code is served from a stored annual edition (`year` 2024, `currentThrough` 2025-01-06), so a section repealed after that edition closed still carries `actStatus: in_force` and survives this filter. Every USC result therefore reports `goodLawStatus: unknown`, which is the honest answer and the one this field's second paragraph tells you to read. Use `/section/{actId}/changes` for the timeline on a section you depend on. - `actStatus` union: Positively scope to one or more raw publisher statuses, e.g. `"repealed"` to find only dead law, or `["in_force"]` for only sections affirmatively marked current. This is the inverse of `excludeRepealed` and is what you want for a compliance diff that asks what was LOST rather than what remains. Values are the statuses this API classifies: `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`. A result's `actStatus` can carry other raw publisher words (`enacted` on session laws, `snapshot`, `pending`); those are not filterable and are rejected with 422, because we cannot say what they mean for whether the law is good. Combining a dead status here with `excludeRepealed: true` contradicts itself and is rejected with 422 rather than silently returning nothing. - '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' - string[] - `changedSince` string, date, nullable: Only return sections we have OBSERVED change on or after this date (`YYYY-MM-DD`). This is the sync filter: it turns a lookup API into something a nightly job can poll, without creating a board watch per jurisdiction. These are observed changes, not effective dates. A refresh compared the publisher against the copy we held and found it different; the date is when we SAW it, an upper bound on when it took effect. It is the same event stream `GET /us/statutes/section/{actId}/changes` serves per section, so a hit here has a history there. Coverage is bounded by capture, not by the age of the law. Change capture began long after the corpus did, it is per-source, and events are swept at 5 years. An empty result means no captured change in the window, never that nothing was amended. Narrow with `corpusType` and `state` for a tighter window: the change set is resolved to concrete sections before the search runs, and a window matching too many sections is rejected with a 422 that says so rather than silently truncating your answer. - `agency` union: Federal Register agency slug, e.g. `environmental-protection-agency`. The agency's full name (`Environmental Protection Agency`) or its Federal Register acronym (`EPA`, `e.p.a.`) resolves to the same slug; an acronym the Federal Register gives to more than one agency (`FS`) or a value naming no agency the corpus holds is a 422, never a charge. Pass a list to match any of several. Applies to `FEDERAL_REGISTER` and `EXECUTIVE_ACTION`; other corpora carry no agency, so combining this with them returns nothing. - string - string[] - `documentType` 'final' | 'proposed' | 'presidential', nullable: Federal Register document stage: `final` (a rule in force), `proposed` (an NPRM), or `presidential` (a Presidential Document, the `EXECUTIVE_ACTION` corpus). The same distinction appears in each row's `actId` prefix (`FR_RULE_` vs `FR_PRORULE_`). - `publishedFrom` string, date, nullable: Only return Federal Register documents published on or after this date (`YYYY-MM-DD`). This is the PUBLICATION date, which is not the same as `yearFrom`: that filters the version year of a section. - `publishedTo` string, date, nullable: Only return Federal Register documents published on or before this date. - `titleNumber` integer, nullable: Filter by USC/CFR title number (e.g., 17 for SEC, 42 for civil rights). Only meaningful for `USC`/`CFR`; ignored for state corpora whose titles are alphabetic (e.g. Texas `pe` = Penal Code). - `chapter` union: Scope a search to one or more chapters within a title or code, e.g. `21` for USC Title 42 Chapter 21. This is the search-side of the `parent` object on each result: pass a hit's `parent.chapter` straight back to search that hit's neighbors. Chapter numbers repeat across titles, so pair it with `titleNumber` (USC) or `code` (state); an unpaired chapter is rejected. String or list. - string - string[] - `part` union: Scope a search to one or more parts within a title, e.g. `240` for 17 C.F.R. Part 240. The CFR counterpart to `chapter`: pass a hit's `parent.part` straight back to search within that part. Pair it with `titleNumber`; an unpaired part is rejected. String or list. - string - string[] - `source` union: Scope to one or more of the following. The named source within `corpusType`, for corpora that fold several independently filterable bodies of law into one token. `FEDERAL_RULES` sources: `frcp` (Federal Rules of Civil Procedure), `frcrp` (Federal Rules of Criminal Procedure), `fre` (Federal Rules of Evidence), `frap` (Federal Rules of Appellate Procedure), `frbp` (Federal Rules of Bankruptcy Procedure), `sct` (Rules of the Supreme Court of the United States). `CFR` sources: `far` (Federal Acquisition Regulation (48 C.F.R. ch. 1)), `dfars` (Defense Federal Acquisition Regulation Supplement (48 C.F.R. ch. 2)) (both are already part of `CFR`; this only splits the existing Title 48 data by chapter, it does not add new sections). `AGENCY_GUIDANCE` sources: `administrative_guidance` (Synthesized administrative guidance (e.g. SALT cap, CTC, 401(k) limits)), `ssa_ruling` (Social Security Administration Rulings), `irs_rev_proc` (IRS Revenue Procedures), `irs_notice` (IRS Notices), `irs_rev_rul` (IRS Revenue Rulings), `irs_announcement` (IRS Announcements), `irs_irm` (Internal Revenue Manual (IRS internal procedure)), `merger_guidelines` (DOJ & FTC Merger Guidelines (2023)), `doj_leniency` (DOJ Antitrust Division Leniency Policy), `doj_business_review` (DOJ Antitrust Division Business Review Letters (1991-2021)), `cms_iom` (CMS Medicare Internet-Only Manuals (instruction to Medicare contractors, not a regulation)), `copyright_circular` (US Copyright Office Circulars), `copyright_compendium` (Compendium of U.S. Copyright Office Practices, Third Edition (2014, 2017 and 2021 editions)), `doj_justice_manual` (DOJ Justice Manual), `uscis_policy_manual` (USCIS Policy Manual), `mpep` (USPTO Manual of Patent Examining Procedure (MPEP)), `tmep` (USPTO Trademark Manual of Examining Procedure (TMEP)), `cftc_staff_letter` (CFTC Staff Letters (no-action, exemptive, interpretative; 2008-present)), `fincen_ruling` (FinCEN Administrative Rulings), `fincen_guidance` (FinCEN Guidance (alerts, advisories, notices, bulletins, fact sheets)), `fincen_boi_faq` (FinCEN Beneficial Ownership Information FAQs), `fincen_boi_rule_qa` (FinCEN BOI Rulemaking Q&As (final rule and interim final rule)), `fincen_boi_compliance_guide` (FinCEN Small Entity Compliance Guide (Beneficial Ownership Information Reporting)), `fincen_amla_material` (FinCEN Anti-Money Laundering Act of 2020 Implementation Material), `frb_sr_letter` (Federal Reserve Supervision and Regulation (SR) / Consumer Affairs (CA) Letters), `occ_bulletin` (OCC Bulletins), `occ_interpretive_letter` (OCC Interpretive Letters), `fdic_fil` (FDIC Financial Institution Letters (FILs)), `cfpb_supervisory_guidance` (CFPB Supervisory Guidance), `cfpb_circular` (CFPB Consumer Financial Protection Circulars), `dfars_pgi` (DFARS PGI (Procedures, Guidance, and Information)), `ftc_advisory_opinion` (FTC Advisory Opinions), `ftc_policy_statement` (FTC Policy Statements (1967-present)), `ftc_hsr_interpretation` (FTC HSR Premerger Notification Interpretations: the Commission's formal interpretations under 16 C.F.R. 803.30 (1978-2000, a closed series) and the Premerger Notification Office's informal interpretations (1983-present; the publisher serves none from 1997)), `ftc_advocacy_filing` (FTC Advocacy Filings: comments and letters to state legislatures, state courts, governors and other federal agencies on the competition effects of a proposed measure (1985-present). Advisory only: they bind nobody and decide no case), `nlrb_gc_memo` (NLRB General Counsel Memoranda), `nlrb_advice_memo` (NLRB Division of Advice Memoranda (rolling 10-year window, not the full archive)), `cpsc_advisory_opinion` (CPSC Office of General Counsel Advisory Opinions (historical, 1970s-2012)), `cpsc_secg` (CPSC Small Entity Compliance Guides), `whd_opinion_letter` (DOL Wage and Hour Division Opinion, Ruling and Administrator Interpretation Letters (FLSA, FMLA, DBRA, SCA, CCPA, MSPA; 1993-present)), `whd_foh` (DOL Wage and Hour Field Operations Handbook (WHD internal enforcement procedure, not law; 22 chapters)), `bis_advisory_opinion` (BIS (Bureau of Industry and Security) Advisory Opinions), `ddtc_commodity_jurisdiction` (DDTC (Directorate of Defense Trade Controls) Commodity Jurisdiction Determinations), `ddtc_guidance` (DDTC (Directorate of Defense Trade Controls) Policy Guidance Documents), `ofac_faq` (OFAC (Office of Foreign Assets Control) Frequently Asked Questions), `hhs_ocr_hipaa_faq` (HHS Office for Civil Rights HIPAA FAQs), `hhs_ocr_hipaa_guidance` (HHS Office for Civil Rights HIPAA Guidance Materials), `hhs_ocr_resolution_agreement` (HHS Office for Civil Rights HIPAA Resolution Agreements and Civil Money Penalties), `fcc_declaratory_ruling` (FCC (Federal Communications Commission) Declaratory Rulings), `ferc_policy_statement` (FERC (Federal Energy Regulatory Commission) Policy Statements), `doe_appliance_guidance` (DOE Appliance Standards Guidance and FAQs), `eeoc_guidance` (EEOC (Equal Employment Opportunity Commission) Enforcement and Policy Guidance, including Compliance Manual sections), `irs_written_determination` (IRS Written Determinations under 26 U.S.C. § 6110: Private Letter Rulings (PLR), Technical Advice Memoranda (TAM) and Chief Counsel Advice (CCA). Each is directed only to the taxpayer who requested it and, by § 6110(k)(3), may not be used or cited as precedent). `US_TAX_TREATY` sources: `us_tax_treaty` (U.S. Bilateral Income Tax Treaties), `us_tax_treaty_technical_explanation` (Treasury Technical Explanations (article-by-article commentary on a tax treaty)). `US_TREATY` sources: `us_treaty` (Treaty and International Agreement Text (Stat., U.S.T., T.I.A.S., Bevans, FATCA agreements, free trade agreements, Social Security totalization agreements)), `senate_treaty` (Senate Treaty Records (transmittal, parties and proceedings)), `senate_treaty_resolution` (Senate Resolutions of Advice and Consent, including the reservations, understandings and declarations that narrow a treaty's effect in US law), `senate_treaty_document` (Treaty Documents (CDOC TDOC series): the President's message transmitting a treaty to the Senate, with the instrument's text), `senate_executive_report` (Senate Executive Reports: the committee's report recommending advice and consent to a treaty, with its analysis of the instrument). `STATE_AGENCY_GUIDANCE` sources: `state_insurance_bulletin` (State Department of Insurance Bulletins), `state_financial_bulletin` (State Financial-Institutions Regulator Bulletins (banking, credit unions, trust companies, escrow agents, consumer lenders, money transmitters; AZ and OR only, where that regulator shares an index with the insurance regulator)). `AGENCY_ADJUDICATION` sources: `mspb_precedential` (MSPB Precedential Decisions), `mspb_nonprecedential` (MSPB Nonprecedential Orders), `olc_opinion` (DOJ Office of Legal Counsel Opinions (official bound volumes, 1933-2020)), `cfpb_enforcement_action` (CFPB Enforcement Actions), `sec_commission_opinion` (SEC Commission Opinions and Adjudicatory Orders), `bia_precedent` (BIA Precedent Decisions (I&N Dec.)), `ag_precedent` (Attorney General Immigration Decisions (I&N Dec.)), `immigration_admin_precedent` (INS and USCIS Administrative Precedent Decisions (I&N Dec.)), `nlrb_board_decision` (NLRB Board Decisions (1935 to date)), `ftc_administrative_decision` (FTC Part 3 Administrative Decisions). Every result carries its own `source`, so you can pass a hit's value straight back. An unrecognized value is rejected with 422. - 'administrative_guidance' | 'ag_precedent' | 'agency_guidance' | 'bia_precedent' | 'bis_advisory_opinion' | 'cfpb_circular' | 'cfpb_enforcement_action' | 'cfpb_supervisory_guidance' | 'cftc_staff_letter' | 'cms_iom' | 'copyright_circular' | 'copyright_compendium' | 'cpsc_advisory_opinion' | 'cpsc_secg' | 'ddtc_commodity_jurisdiction' | 'ddtc_guidance' | 'dfars' | 'dfars_pgi' | 'doe_appliance_guidance' | 'doj_business_review' | 'doj_justice_manual' | 'doj_leniency' | 'eeoc_guidance' | 'far' | 'fcc_declaratory_ruling' | 'fdic_fil' | 'ferc_policy_statement' | 'fincen_amla_material' | 'fincen_boi_compliance_guide' | 'fincen_boi_faq' | 'fincen_boi_rule_qa' | 'fincen_guidance' | 'fincen_ruling' | 'frap' | 'frb_sr_letter' | 'frbp' | 'frcp' | 'frcrp' | 'fre' | 'ftc_administrative_decision' | 'ftc_advisory_opinion' | 'ftc_advocacy_filing' | 'ftc_hsr_interpretation' | 'ftc_policy_statement' | 'hhs_ocr_hipaa_faq' | 'hhs_ocr_hipaa_guidance' | 'hhs_ocr_resolution_agreement' | 'immigration_admin_precedent' | 'irs_announcement' | 'irs_irm' | 'irs_notice' | 'irs_rev_proc' | 'irs_rev_rul' | 'irs_written_determination' | 'merger_guidelines' | 'mpep' | 'mspb_nonprecedential' | 'mspb_precedential' | 'nlrb_advice_memo' | 'nlrb_board_decision' | 'nlrb_gc_memo' | 'occ_bulletin' | 'occ_interpretive_letter' | 'ofac_faq' | 'olc_opinion' | 'sct' | 'sec_commission_opinion' | 'senate_executive_report' | 'senate_treaty' | 'senate_treaty_document' | 'senate_treaty_resolution' | 'ssa_ruling' | 'state_financial_bulletin' | 'state_insurance_bulletin' | 'tmep' | 'us_tax_treaty' | 'us_tax_treaty_technical_explanation' | 'us_treaty' | 'uscis_policy_manual' | 'whd_foh' | 'whd_opinion_letter' - string[] - `fields` union: Return only these result fields, e.g. `["title", "excerpt"]`. A result carries 40+ fields and most are null on any given row, so a full page of 50 ships a lot of nulls. `actId` and `citation` are always included, because a row without them cannot be used or attributed. Unknown names are rejected with 422 so a typo does not silently drop a field you needed. Omit for the full object. The `required` list on the result schema describes the full object; a response narrowed with `fields` carries only the fields you named. - string[] - string[] - `matchType` 'any' | 'all' | 'phrase' | 'boolean': Controls exact vs. semantic matching. `any` (default) is hybrid semantic + keyword ranking and suits natural-language questions. Use `all` for strict keyword matching (every query word must appear in the text) or `phrase` for an exact-phrase match (the query's words, contiguous and in order). Both match whole words, case-insensitively, ignoring punctuation: `act` does not match `fact`, `10b-5` matches `10b 5`, and `§ 1983` matches `section 1983`. Both are answered from the full text of every section in scope, so a section holding the words is found however the relevance ranking would have placed it, and they page like `boolean`. `boolean` reads `query` as a terms-and-connectors expression and returns only sections that satisfy it, judged over each section's full text, ranked by relevance among them. Operators are UPPERCASE: `AND`, `OR`, `NOT` (`negligence NOT criminal`), `/p` same paragraph, `/s` same sentence, `/N` within N words (1-255), `+p` `+s` `+N` the same with the first term first, `atleastN(term)` at least N occurrences, `"exact phrase"`, and bare words side by side are also an exact phrase (`summary judgment`). Wildcards: `retaliat*` or `retaliat!` (any letters or digits), `wom?n` (one character), with at least 3 characters first. Group with `( )`. Precedence follows the convention of legal research services: `OR` binds tightest, then `/N`, `/s`, `/p`, then `AND`, then `NOT`. A malformed expression is a 422 naming the problem and its position, and is not charged; the response's `parsedQuery` shows how the expression was read. To pull up one specific section, pass its citation as the query with `any` (e.g. `42 U.S.C. § 1983`) and it resolves to that section at rank 1. - `limit` integer: Number of results to return per page. - `offset` integer: How many results to skip, for paging. Every page of a given query is cut from one ranking, so results never repeat or go missing between pages, and a later page costs no more than the first. `any` ranks one bounded pool of about 60 sections plus up to about 30 more from the law-specific legs, so roughly 60 to 90 results are reachable and `hasMore` turns false at the end of that pool, which can be before `offset` 70. `offset` is at most 70 there. For exhaustive paging use `matchType: "boolean"`, `all` or `phrase`, which page to the end of the matches (up to 10,000): follow `nextOffset`. - `includeBody` boolean: Return the full text of every hit inline, on each result's `body`, instead of making you fetch it per section afterwards. Why it exists. Search returns a ranking preview, so the alternative is a search call plus one `/section/{actId}/body` call per hit. This collapses a whole page to a single round trip. Cost: the 4-credit search PLUS the ordinary 6-credit body price for each row that actually returns text. Ten rows with text is 4 + 60 = 64 credits. A row whose text cannot be resolved comes back with `body: null` and is not charged, so read `creditsConsumed` rather than computing it from `limit` -- it is the same price as fetching them yourself, so this buys latency, not a discount. ⚠️ It multiplies with `limit`. `limit: 50` with this set is 304 credits in a single call. Page deliberately. `includeBody` wins over `fields`: if `fields` omits `body`, `body` is added to it (and `notes` says so), so every body you are billed for is in the response. Prefer this over raising `excerptChars`: the excerpt is windowed around the match and can begin mid-section, dropping a leading subsection marker, so it is not safe to quote. `body` is the publisher's text. - `includePinpoint` boolean: Name the subsection each hit matched, in a `pinpoints` object keyed by `actId`. Search ranks whole sections, and a section can run to dozens of subsections; with this set, a hit for `30 mph urban district speed limit` comes back with `625 ILCS 5/11-601(c)(1)`, its own text, the lead-in it completes and its character offsets in the section's `plain` text. Cost: none. The price is the search price and `creditsConsumed` does not change. It never changes which sections are returned, their order or their scores, and it never fails the search: a hit whose subsection cannot be named says why in `reason` and is still a real match. A subsection is named only when your query's words point at it, so a question put in other words than the law's gets `located: false` rather than a guess. Time: adds the time to read each returned section's text, usually a few hundred milliseconds for a page of 10. Pinpoints for a large page stop after a few seconds, and the hits not reached say `not_looked_up`. - `excerptChars` integer: Characters of matching text to include in each result's `excerpt`, 100 to 600. The excerpt is a ranking preview, deliberately too short to stand in for the section; use `/us/statutes/section/{actId}/body` (or `includeBody`) for the full text. Default 500. A larger value is a 422. ## Response `200` Ranked sections for the query. - StatuteSearchResponse - `results` StatuteResult[]: Matching sections, most relevant first. Ordering is by relevance, not statutory order; use `/us/statutes/section/{actId}/related` for what sits either side of a section in its code. - `actId` string, required: Unique section identifier (e.g., 'USC_T42_C21_S1983', 'CFR_T17_P240_S240_10b5_1'). - `citation` string, nullable, required: Full citation (e.g., '42 U.S.C. § 1983 (2024)', '17 C.F.R. § 240.10b5-1 (2026)'). Always present; null when not known. - `citationShort` string, nullable, required: Short citation (e.g., '42 U.S.C. § 1983', '17 C.F.R. § 240.10b5-1'). Always present; null when not known. - `title` string, nullable, required: Section title. Always present; null when not known. - `corpusType` string, nullable, required: The corpus this section belongs to: one of `USC`, `CFR`, `STATE`, `CONSTITUTION`, `FEDERAL_RULES`, `FEDERAL_LOCAL_RULES`, `STATE_CONSTITUTION`, `STATE_RULES`, `EXECUTIVE_ACTION`, `REGULATION`, `FEDERAL_REGISTER`, `FEDERAL_REGISTER_NOTICE`, `AGENCY_GUIDANCE`, `SENTENCING_GUIDELINES`, `US_TAX_TREATY`, `US_TREATY`, `STATE_AGENCY_GUIDANCE`, `STATE_AG_OPINION`, `STATE_REGISTER`, `SESSION_LAW`, `STATUTE_COMPILATION`, `AGENCY_ADJUDICATION`, `CFR_ANNUAL`, `USC_ANNUAL`, `FEDERAL_BILL`, `FEDERAL_RULES_ANNUAL`, `FEDERAL_RULES_PROPOSED`. The same tokens the `corpusType` filter accepts. Always present; null when not known. - `state` string, nullable, required: 2-letter lowercase state code (e.g. `ca`, `tx`) when the row belongs to a state corpus. `federal` for federal rows. Always present; null when not known. - `source` string, nullable, required: The named source within `corpusType` this row belongs to, for corpora that fold several bodies of law into one token. Pass it back as the `source` search filter to scope to just this source; the accepted values, with their names, are listed on that filter. Null for corpora with only one source, which includes every state's statutes and regulations. Not a link, and not where the text came from: it is a filter token. The official link to the publisher's text is `sourceUrl`. - `year` integer, nullable, required: The year this row was ingested, not the year of the law. Most ingesters stamp the capture year (`time.gmtime().tm_year`) and a few pin a literal, so the bulk of the corpus reads the year it was captured. Do not filter or reason about currency with it. `lastAmendedYear` carries the amendment year, `currentThrough` and `currencyNote` carry the publisher's own currency statement, and `goodLawStatus` carries the status. Always present; null when not known. - `relevanceScore` number, nullable, required: Relevance score, normalized to roughly 0-1. Higher means a better match for ranking within one response. It is a relative ranking signal, not a calibrated confidence or probability, so do not compare scores across different queries or treat a fixed value as a quality threshold. Exception: a query that resolves to an exact citation (e.g. '42 U.S.C. § 1983', 'Cal. Civ. Code § 1950.5', 'Fed. R. Civ. P. 12') always scores that section 1.0, since it is a certain match rather than a ranked one -- a natural-language or keyword query never returns 1.0 by comparison. null on any endpoint that did not rank: fetching a section by id, a batch fetch, or a section embedded in an intelligence response. When the response carries `rankingDegraded: true`, the relevance model was unavailable and this is a retrieval score on a different, much smaller scale: still a valid ORDER, not a 0-1 relevance. - `excerpt` string, required: Text excerpt (up to 500 characters). - `body` string, nullable, required: Full plain text of the section. Always a key on the row: filled only when the request set `includeBody: true`, and null otherwise and on any row whose text could not be resolved (those rows are not charged for a body). A section the publisher prints as images has no text: its `body` is null and `bodyUnavailable` is `true`. This is the actual statutory text, not the `excerpt`. The two are different things and the difference matters for quoting: `excerpt` is a ranking preview windowed around the match, so it can begin mid-section and drop a leading subsection marker -- measured 2026-09-02, four of five California rows lost their opening `(a) `. `body` is the document as the publisher printed it. - `bodyUnavailable` boolean, nullable: Present, and `true`, only on a section that has no text to return: the publisher prints it as images (an appendix, a form, a map), or the text we hold is only a partial copy of the official text. Omitted on every other section. The section is real and its metadata is complete; there is simply no body, so `body` / `plain` / `html` are null, `available` is false on `/body`, and nothing is charged for a body. Read it instead of treating a null body as a fetch failure that is worth retrying. - `bodyUnavailableReason` 'image_only_source' | 'misfiled_source_text' | 'partial_snapshot_text', nullable: Why there is no body, present with `bodyUnavailable`. `image_only_source`: the publisher prints this section as images, so there is no text to extract. Where we hold an official link for the section it is in `sourceUrl`; it is null where we may not republish the publisher's link. `misfiled_source_text`: the text stored under this regulation opens with another rule's number (a prior version filed under a renumbered rule), so it is withheld rather than served as this rule. `partial_snapshot_text`: the text we hold for this section is only a partial copy of the official text, so it is withheld rather than served as if it were complete. Omitted from the response when it has no value. - `bodyNote` 'fetch_failed' | 'no_text' | 'insufficient_credits' | 'response_size_cap', nullable: Present only when the request set `includeBody: true` and this row's `body` is null for a reason on our side or yours, so a null body is never silent. `fetch_failed`: reading the text failed this time, retry; not charged. `no_text`: the read succeeded but returned no text for this section; not charged. `insufficient_credits`: your balance could not cover the bodies, so every body on the page was withheld (the ranking you paid for is intact); top up and repeat the call. `response_size_cap`: a batch response carries at most 4,000,000 characters of inline body text, and this row's body was dropped to stay under it; not charged, fetch it from `/section/{actId}/body`. A section printed as images carries `bodyUnavailable` instead. - `bodyServedNote` string, nullable: Present only when the request set `includeBody: true` and the `body` on this row is not the section's preferred copy: a lesser copy was served because the preferred one could not be read this time, a rendered table or figure was withheld, or the text is partial. The same words `/section/{actId}/body` returns in `note`. Not cached, so a repeat call may return the preferred copy. - `matchContexts` BooleanMatchContext[], nullable: Present only with `matchType: "boolean"`: up to 3 passages showing where this section satisfied the expression, in the order they appear in the section. Highlights follow the engine that decides membership: every conjunct of an AND, the OR branches that matched, the words of a phrase, both operands of a satisfied `/N`, `/s` or `/p` pair, the occurrences counted by `atleastN`, and for `a NOT W/N b` the `a` that has no `b` in range. A NOT never highlights anything. Unlike `excerpt` (the passage the relevance model ranked, which may not contain your terms), these passages always do. Empty (`[]`) when the expression matched only in the heading or citation (`title( )`, `cite( )`). Absent on a row whose passages could not be prepared within the search's time allowance; the row is still a verified match. Contexts never change which sections are returned, their order, or the price. - `text` string, required: About 240 characters of the section's text as published, cut on word boundaries, with each run of whitespace (line breaks included) shown as one space and soft hyphens removed (a word hyphenated across a line break is joined). It can begin and end mid-sentence. - `highlights` array[], required: The words that satisfied the expression, as `[start, end]` character offsets into `text` (start inclusive, end exclusive, counted in Unicode code points, so `text.slice(start, end)` in JavaScript holds only for text without astral characters; Python's `text[start:end]` always does). Sorted, never overlapping. Offsets point at the text as printed, which matching normalizes: a highlight for `section` can cover `§`, one for `café` can cover `CAFÉ` or a decomposed accent, and one for a phrase covers the whole phrase. Plain offsets, not markup, so you choose how to style them. - integer[] - `titleNumber` string, nullable, required: USC/CFR/state title number (e.g. '26', '13A'). Always present; null when not known. - `titleName` string, nullable, required: Title name (e.g., 'The Public Health and Welfare'). Always present; null when not known. - `chapter` string, nullable, required: Chapter number or identifier. Always present; null when not known. - `chapterName` string, nullable, required: Chapter name. Always present; null when not known. - `sectionNumber` string, nullable, required: Section number (e.g., '1983', '240.10b5-1'). Always present; null when not known. - `sectionTitle` string, nullable, required: The section's own heading (e.g., 'Rule G. Forfeiture Actions In Rem'). Distinct from `title`, which is the hierarchical display path. Always present; null when not known. - `displayPath` string, nullable, required: Full hierarchical path (Title > Chapter > Section). Always present; null when not known. - `breadcrumb` object[], nullable, required: Structured breadcrumb trail for navigation. Always present; null when not known. - `parent` object, nullable, required: Query for `GET /us/statutes/divisions` that lists this section's siblings (its containing chapter, part, code, article or federal rule set). Pass it straight back to walk up the hierarchy, or spread it into a `POST /us/statutes/search` body to search within that container: every key it carries is also a search filter. Null when the container cannot be determined. - `subchapter` string, nullable, required: Subchapter number or identifier. Always present; null when not known. - `subchapterName` string, nullable, required: Subchapter name. Always present; null when not known. - `part` string, nullable, required: Part number or identifier (CFR/state). Always present; null when not known. - `partName` string, nullable, required: Part name. Always present; null when not known. - `subpart` string, nullable, required: Subpart number or identifier (CFR). Always present; null when not known. - `subpartName` string, nullable, required: Subpart name. Always present; null when not known. - `popularName` string, nullable, required: Popular/common name of the act (e.g. 'Truth in Lending Act'), when known. Always present; null when not known. - `actStatus` string, nullable, required: Raw section status: `in_force`, `repealed`, `renumbered`, `transferred`, `omitted`, `reserved`, `vacant`, or `unconstitutional`. Some corpora also use `superseded` (a prior version), `enacted`, `pending` and `non_precedential`. This is the status recorded for the section; the currency verdict is `goodLawStatus`. Always present; null when not known. - `goodLawStatus` string, nullable, required: Derived currency verdict: `good_law`, `not_good_law`, `not_operative`, or `unknown`. `unknown` means no currency verdict is asserted for the section, which is different from out of date. It is returned where a jurisdiction does not publish repeal information (state statutes for California, for example, are stored `in_force` with `goodLawStatus: unknown`: the stored status is the publisher's own, and we do not certify it current because that state's repeal markers have not been verified), and for these corpora by design: attorney general opinions, register notices, statute compilations, the U.S. Code, executive actions and treaties. Annual editions (`cfr_annual`, `usc_annual`) return `not_good_law` because a later edition supersedes them. Read `corpusType` beside this field. `null` when currency checking is disabled. - `goodLawBasis` string, nullable, required: Why `goodLawStatus` has the value it has, as a short code; `null` exactly when `goodLawStatus` is `null`. `good_law`: `in_force` (recorded in force, in a jurisdiction whose repeal information we track). `not_good_law`: `repealed_or_moved` (repealed, renumbered, transferred or recodified), `past_edition` (an annual edition later editions supersede), `proposal` (a bill or proposed rule, never law at any stage), `superseded_by_later_guidance` (IRS guidance a later document superseded, obsoleted or revoked in full), `later_rule_removed` (a Federal Register final rule a later final rule removed from the CFR) or `later_order_revoked` (an executive order a later one revokes or supersedes in full). For the last three `supersededBy` names the later document, and for the last `actStatus` reads `revoked` or `superseded`. `not_operative`: `reserved_or_inactive` (reserved, vacant or unfunded), `not_yet_effective` (a future effective date is printed in the heading, or a final rule's `frEffectiveOn` is ahead) or `publisher_marker` (the publisher's own bracketed note in the heading). `unknown`: `no_repeal_signal` (the publisher gives no repeal markers to check its stored status against), `frozen_snapshot` (served from an edition frozen at a past date), `stated_as_of_date` (current only to the date the text states), `no_status`, `text_omitted_by_publisher` (the legislature prints only a placeholder such as 'Amendatory provisions; text omitted'; `currencyNote` says so) or `status_unrecognized`. - `currencyNote` string, nullable, required: Source's 'current through ...' note, when published. Always present; null when not known. - `renumberedTo` string, nullable: Where the publisher says this section went, when `actStatus` is `renumbered`. RAW SOURCE FORM, not an `actId` and not a citation: `self:4651` means section 4651 of this same title, `34:10105` means section 10105 of Title 34. Do not pass it to a section endpoint. Read `renumberedToLabel` instead, or resolve the citation it names through `/us/statutes/resolve`. Omitted from the response when it has no value. - `renumberedToLabel` string, nullable: `renumberedTo` written out, e.g. `section 10105 of Title 34`. Present whenever `renumberedTo` is. Omitted from the response when it has no value. - `transferredTo` string, nullable: Where the publisher says this section went, when `actStatus` is `transferred`. Same raw source form as `renumberedTo`, and the same warning: it is not an `actId`. Omitted from the response when it has no value. - `transferredToLabel` string, nullable: `transferredTo` written out. Present whenever `transferredTo` is. Omitted from the response when it has no value. - `issueDate` string, nullable, required: Issue/publication date of this version, as `YYYY-MM-DD`, when known. See `issueDateRaw` for the publisher's wording on the rare source that does not print ISO. Always present; null when not known. - `issueDateRaw` string, nullable: The issue date as the publisher writes it, present only when it differs from `issueDate`. Null across the corpus today; it exists so a source that starts printing prose cannot silently put prose in a field documented as a date. - `crossReferencesCfr` string[], nullable: CFR cross-references parsed from the text, e.g. `['1.6011-4']`. Omitted from the response when it has no value. - `crossReferencesCfrChecked` CfrReferenceCheck[], nullable: Each distinct entry of `crossReferencesCfr`, checked against the sections we hold. Only populated on `GET /us/statutes/section/{actId}` for a CFR section with references; null on search results and when the check could not be made, in which case treat the raw list as unchecked. Omitted from the response when it has no value. - `reference` string, required: The reference exactly as stored in `crossReferencesCfr`. - `title` integer, nullable: CFR title the reference names or was assumed to name. Null if malformed. - `section` string, nullable: Section number with sentence punctuation removed (`80.1426.` is `80.1426`). - `status` 'held' | 'not_held' | 'malformed', required: `held`: this exact section is in the corpus (fetch it by `actId`). `not_held`: no section with this exact number is held in that title; it may be a truncated stem, a part we do not hold or an extraction error. We never substitute a nearby section. `malformed`: not shaped like a CFR section number. - `actId` string, nullable: The held section's id, when `held`. - `titleAssumed` boolean: True when the reference carried no title and the citing section's own title was assumed. Such a reference can point at another title. - `crossReferencesUsc` string[], nullable: USC cross-references parsed from the text, e.g. `['42:1983']`. `'self:
'` denotes a reference to another section of the same title. Omitted from the response when it has no value. - `statutoryAuthority` object[], nullable: For a CFR/eCFR section: the USC (or other) citations in its 'Authority' note that authorize the rule, e.g. `[{'type': 'usc', 'title': 15, 'section': '78o', 'display': '15 U.S.C. 78o'}]`. Null for non-regulation corpora. Omitted from the response when it has no value. - `implementingRegulations` object[], nullable: For a USC section: the CFR parts that implement it, derived from the reverse of every CFR section's own `statutoryAuthority`, e.g. `[{'cfrTitle': 17, 'part': '240', 'partName': '...', 'display': '17 CFR Part 240'}]`. Null for non-USC corpora. Omitted from the response when it has no value. - `frRegulationIdNumbers` string[], nullable: Regulation Identifier Number(s) (RIN) assigned to this rule. Omitted from the response when it has no value. - `frDocketIds` string[], nullable: Rulemaking docket ID(s) this document was filed under. Omitted from the response when it has no value. - `frEffectiveOn` string, nullable: The rule's effective date (ISO 8601 date), when set. Omitted from the response when it has no value. - `frCommentsCloseOn` string, nullable: Public-comment deadline (ISO 8601 date). Proposed rules only. Omitted from the response when it has no value. - `frSignificant` boolean, nullable: Whether the Federal Register marked this rule 'economically significant' (EO 12866). Omitted from the response when it has no value. - `frCorrectionOf` string, nullable: Federal Register document number this document corrects, when this is a correction. Omitted from the response when it has no value. - `frCorrections` string[], nullable: Federal Register document number(s) that later corrected this document. Omitted from the response when it has no value. - `frRegulationsDotGovUrl` string, nullable: Link to this document's public comment docket on regulations.gov. Omitted from the response when it has no value. - `frRelatedDocuments` FrRelatedDocument[], nullable: Other Federal Register documents sharing this document's RIN(s) (its proposed rule, its final rule, and any corrections), most recent first. Only populated on `GET /us/statutes/section/{actId}` for a row that carries `frRegulationIdNumbers`; always null on `/us/statutes/search` results, since computing it needs a follow-up lookup that is too expensive to run per search result. Omitted from the response when it has no value. - `actId` string, required - `citation` string, nullable - `title` string, nullable: The related document's own title/heading, when known. - `documentType` string, nullable: `proposed_rule`, `final_rule`, or the raw Federal Register category otherwise. - `publicationDate` string, nullable: Federal Register publication date (ISO 8601 date), when known. - `frRelatedDocumentsNote` string, nullable: Set only when `frRelatedDocuments` is absent for a reason you should know: this document's RIN is shared by more than 25 other Federal Register documents (an umbrella RIN), so it names no single rulemaking and listing any subset would be a guess; or the related-document lookup was temporarily unavailable, so the list may be incomplete and a repeat call returns it. In that case the call is refunded (`creditsConsumed` is 0). Omitted from the response when it has no value. - `subject` string, nullable: The publisher's own subject or document-type label, where it prints one (for example a state insurance bulletin's `RE:` line, or its listing category such as `Rescission`). Omitted from the response when it has no value. - `rescindedOn` string, nullable: The date the document was rescinded or withdrawn, as `YYYY-MM-DD`, when the source states one. See `rescindedOnRaw`. Omitted from the response when it has no value. - `rescindedOnRaw` string, nullable: The rescission date as the publisher writes it, present only when it differs from `rescindedOn`. - `sourceCredit` string, nullable: The Office of the Law Revision Counsel's credit line for a USC section: the acts that enacted and amended it, in order, e.g. `June 25, 1948, ch. 646, 62 Stat. 869; Pub. L. 85-508, Sec. 12, July 7, 1958, 72 Stat. 348`. Parentheses stripped, whitespace normalized. USC only, and null on a USC section that prints no credit (a transferred, repealed or reclassified stub). CFR sections carry the same fact as a list in `federalRegisterCitations` instead, which is why the shape differs; no other corpus publishes one. Omitted from the response when it has no value. - `amendmentYears` integer[], nullable, required: Distinct years the section was amended, parsed from the publisher's history note. Always newest first, and de-duplicated. Ingesters store the array in both orders (eCFR writes newest first, state regulations and state statutes write oldest first), so the order is imposed at serve time and the served order is the only one to rely on. Years outside 1789..(current year) are dropped rather than served: amendment dates are parsed out of prose and a note can yield a sunset or substitution date that is not an amendment at all. Always present; null when not known. - `lastAmendedYear` integer, nullable, required: Most recent amendment year, when known. Re-derived at serve time as `max(amendmentYears)`, so it never exceeds the list served beside it. Falls back to the publisher's own scalar only when `amendmentYears` is empty, and only when that scalar is itself within 1789..(current year). Always present; null when not known. - `amendmentsCount` integer, nullable, required: How many amendments the publisher recorded for this section. Not the length of `amendmentYears`, and it is not safe to derive one from the other. For regulations and court rules this counts amending EVENTS: one per register citation, filing or history entry, so a section amended twice in the same year counts 2 against a single entry in `amendmentYears`. The two disagree on a large share of the regulation and court-rule corpora, so read each for what it is. For the other corpora, and for any source that publishes no per-event record, it is the number of distinct years and is capped at the length of `amendmentYears`, so it never counts a year the list dropped as implausible; it understates a section amended twice in one year. Always present; null when not known. - `currentThrough` string, nullable, required: How current the publisher says this text is, in the publisher's own terms. A date (`2025-01-06`) on every USC section and most compilations; otherwise the publisher's wording (`Current through Act 9046 of the 2025 session`, `Public Law 119-60`, `Supp. 19-2`, `2024 Edition`). Do not parse it as a date without checking its shape. `currencyNote` carries the same fact as prose where a publisher writes it that way. Always present; null when not known. - `pendingAdoptions` object[], nullable: New York only. State Register adoption notices that post-date the print volume this section's text was taken from. They are notices, not an updated consolidated text: `text` and `body` still reflect `currentThrough` / `currencyNote`. Look the notice up in the State Register by its `idNo`. Each entry: `idNo` (e.g. `DFS-23-26-00013-A`), `scope` (`section` when the notice names this section, `part` when it names the Part containing it), `effectiveDate` (ISO date, null if the notice states none), `agency`, `issueDate` (ISO date of the Register issue). No link is returned; it is withheld under licence, as with `sourceUrl` on these regulations. Only adoptions (`-A`, `-AA`) are listed, never proposals, emergency rules or withdrawals. Null on every section with no such notice, which does not mean the section is current: we cover Register adoptions for NYCRR Titles 3, 19 and 23 only. Omitted from the response when it has no value. - `adoptedAfterCurrentThrough` boolean, nullable: New York only. True when `pendingAdoptions` is non-empty, i.e. the State Register records at least one adoption naming this section or its Part that post-dates the volume `currentThrough` refers to, so the text served may be out of date. Null (never false) when no such adoption is recorded; null is not a claim that the text is current. Omitted from the response when it has no value. - `amendmentHistory` string[], nullable: Structured amendment entries where the publisher records them separately from the credit line in `history`. Omitted from the response when it has no value. - `amendmentHistoryNote` string, nullable: Present only when the section carries no amendment evidence and its state or document type does not record enough amendment history to read absence as a fact (for example New York, Massachusetts, Arizona and West Virginia statutes, several states' regulations, court rules and constitutions, opinions, register notices, bulletins, annual CFR editions and session laws). It says `amendmentYears`, `lastAmendedYear` and `amendmentsCount` are absent because nothing was recorded, not because the section is unamended; `amendmentsCount` is then null rather than 0. Also present on a Maryland section whose `history` is generated from General Assembly session data rather than a publisher credit line. Null where history is recorded, and an empty history there does mean the section has not been amended. - `fieldAbsenceNote` string, nullable: Present only when `year` or `effectiveDate` is null AND the ingester of this whole document type never records it (state constitutions carry no `year`; federal local court rules rarely carry a `year` or `effectiveDate`, as of 2026-10-31). It says the field is null because nothing was recorded, which is not a claim that the document has no such date. Null otherwise. - `citationNote` string, nullable: Present only on a state-constitution unit the source gives no section number (an amendment, preamble, schedule or whole article). `citation` is then the article-level form without a section sign, and `sectionNumber` is null. Absent otherwise. - `responseBounds` ResponseBounds: Whether the default response is the whole record, and if not, what is missing. - `truncated` boolean, required: True when at least one field below was shortened. False means this response carries the whole record. Nothing is dropped silently: every shortened field is listed in `fields`. - `fields` BoundedField[]: Every field shortened in this response. Empty when `truncated` is false. - `field` string, required: The response field that was shortened, by its response name. - `unit` 'items' | 'characters', required: `items` for a list, `characters` for the verbatim `history` credit line. - `total` integer, required: How many items (or characters) the record holds. - `returned` integer, required: How many items (or characters) this response carries. - `nextOffset` integer, required: Zero-based position of the first omitted item (or character) in the full value. What follows it is the omitted part: request `full=true` to receive it. - `note` string, nullable: Plain-language statement of what was cut and how to get all of it. Present only when `truncated` is true. - `sourceNote` string, nullable: The publisher's source note for the section, verbatim. Omitted from the response when it has no value. - `effectiveDate` string, nullable, required: When THIS version took effect, as `YYYY-MM-DD`, or null when the publisher's own string does not name one unambiguous day we can read without guessing. On a section with `actStatus=superseded` this is the start of that version's window. The publisher's wording is preserved in `effectiveDateRaw` whenever it differs. - `effectiveDateRaw` string, nullable: The date exactly as the publisher writes it, present only when it differs from `effectiveDate`. A section whose publisher already prints ISO leaves this null. Expect prose (`September 8, 1916`), abbreviated months (`Feb. 25, 1868`), US numerics (`9/28/15`), Spanish for Puerto Rico (`26 de junio de 1963`), and values that are not a single date at all (`April 1, 2023 to June 30, 2026`), which is why they cannot be published under `effectiveDate`. - `historyEffectiveDate` string, nullable, required: When this version took effect, as `YYYY-MM-DD`, read out of the publisher's amendment credit line in `history`, which is returned beside it as the evidence. A weaker fact than `effectiveDate` (a date the publisher put in a date field), so it is populated only where `effectiveDate` is null. It is the newest commencement the credit line names, and null whenever that cannot be stated without guessing: a credit line that dates only some entries, a date that belongs to a repeal, sunset, applicability rule or another section, a commencement still in the future, a date older than `lastAmendedYear`, or a state whose `history` format we have not measured. Statutes only. - `priorEffectiveDates` string[], nullable: Earlier effective dates recorded for the section, each as `YYYY-MM-DD`, in the order the publisher lists them. A publisher's list written as one string (`3-15-22; 7-1-26`) is split into its dates. A value that names no single day (`March 2007`, `immediately`) is not here: it is in `priorEffectiveDatesRaw`. Omitted from the response when it has no value. - `priorEffectiveDatesRaw` string[], nullable: The publisher's own wording of `priorEffectiveDates`, one string per stored entry, present only when it differs from the ISO list or holds an entry that names no single day. Nothing the publisher recorded is dropped. - `history` string, nullable, required: The publisher's own amendment/history credit line, verbatim, e.g. `Effective 5/4/2005; Superseded 8/1/2016`. `amendmentYears` is parsed from this; keep both when you need the exact wording. Always present; null when not known. - `supersededBy` string, nullable: `actId` of the section that replaced this one. Present on a superseded version so you can fetch the current text in one hop via `GET /statutes/section/{actId}`. Omitted from the response when it has no value. - `supersedes` string, nullable: `actId` of the earlier version this section replaced, when known. Omitted from the response when it has no value. - `pendingAmendments` PendingAmendment[], nullable: Federal Rules only: the amendments proposed to this rule that are not yet in force, each with its lifecycle `status`, `cycle`, `effectiveDate`, `commentPeriodEnd`, `sourceUrl` and `textComplete`. Fetch one with `GET /us/statutes/section/{id}`. Absent on every other section and on a rule with nothing pending. A proposal is never law until its effective date: the text above is the rule in force. - `id` string, required: `actId` of the proposed amendment. Fetch it with `GET /us/statutes/section/{id}` or `/body`; it is never returned by an unscoped search. - `status` string, nullable: Where the proposal is in the Rules Enabling Act process: `published_for_comment`, `approved_by_standing_committee`, `approved_by_judicial_conference`, `transmitted_to_supreme_court`, `adopted_by_supreme_court` or `transmitted_to_congress`. A proposal that is in force or withdrawn is not listed here. - `cycle` integer, nullable: The rules cycle (the year the amendment is meant to take effect). - `effectiveDate` string, nullable: The date the amendment takes effect if it is adopted unchanged (ISO 8601 date). - `commentPeriodEnd` string, nullable: Last day of the public comment period (ISO 8601 date), when one applies. - `sourceUrl` string, nullable: The official page the proposal was taken from, when we hold a link we may publish. - `textComplete` boolean, nullable: `true` when the proposed text we hold is the whole amended rule; `false` when it is partial (for example only the changed paragraphs). - `commentDocketIds` string[]: Rulemaking docket ids that hold the public comments on this proposal. Each resolves on `GET /us/rulemaking/dockets/{docketId}`. Empty when none is known. - `ruleSet` string, nullable: For court rules, the rule family this belongs to, e.g. `North Dakota Rules of Civil Procedure`. Rule numbers repeat across families (a Civil Rule 12 and a Criminal Rule 12 both exist), so this is what disambiguates them. Omitted from the response when it has no value. - `publicLaws` string[], nullable: Public Laws referenced by the section, e.g. `['Pub. L. 96-170']`. Omitted from the response when it has no value. - `federalRegisterCitations` string[], nullable: Federal Register citations associated with the section, e.g. `['48 FR 3956', '49 FR 15073']`. This is the CFR's form of the credit line `sourceCredit` carries for the USC: the rulemakings that established and amended the section. Populated on 37.4% of CFR sections, empty where eCFR prints no source note. Omitted from the response when it has no value. - `granuleId` string, nullable: govinfo granule identifier (USC/CFR provenance). Omitted from the response when it has no value. - `packageId` string, nullable: govinfo package identifier (USC/CFR provenance). Omitted from the response when it has no value. - `htmlUrl` string, nullable, required: HTML version of the statute section. Always present; null when not known. - `pdfUrl` string, nullable, required: PDF version of the statute section. Always present; null when not known. - `xmlUrl` string, nullable, required: XML version of the statute section. Always present; null when not known. - `textUrl` string, nullable, required: Plain-text version of the section, from the open-data copy we hold in our own storage. Populated for many state corpora (MS, NJ, NY, NV, etc.) and for United States Code sections. The URL is public by design: the text is open data, so it opens without an API key and carries no credit charge. Null when we hold no plain-text copy. It is never a commercial platform's link. - `docxUrl` string, nullable: Microsoft Word (DOCX) version, when available. Omitted from the response when it has no value. - `stateHtmlUrl` string, nullable, required: HTML rendering of the document. For most state corpora this is the publisher's own page; for corpora we mirror (state agency guidance, regulations, court rules) it is our archived copy of the artifact the publisher served, on statutes-us.vaquill.ai. Use `externalUrl` for the publisher's canonical address. Never a PDF: a mirrored PDF is served as `pdfUrl` instead. Populated for state corpora only. Always present; null when not known. - `govInfoHtmlUrl` string, nullable: Official govinfo.gov HTML version. Omitted from the response when it has no value. - `govInfoPdfUrl` string, nullable: Official govinfo.gov PDF version. Omitted from the response when it has no value. - `abstract` string, nullable: The issuing agency's own summary of the document, as published in the Federal Register. Populated on 99.9% of rules and proposed rules, so a document can be triaged without fetching the full text. Omitted from the response when it has no value. - `agencies` string[], nullable: Issuing agencies, by name. Populated on 99.9% of Federal Register documents. Pair with `agencySlugs` when you need the token the `agency` search filter takes. Omitted from the response when it has no value. - `agencySlugs` string[], nullable: The issuing agencies as slugs. These are exactly the values the `agency` filter on `/us/statutes/search` accepts, so an agency facet can be round-tripped straight back into a query. Omitted from the response when it has no value. - `topics` string[], nullable: The Federal Register's own CFR-index subject terms. Populated on ~71% of rules and ~68% of proposed rules, with one hard boundary: documents published before 2000 carry none, because the Federal Register did not index them this way. Omitted from the response when it has no value. - `documentTypeLabel` string, nullable: The instrument type as the publisher names it: `Rule`, `Proposed Rule`, `Presidential Document`, `Declaratory Ruling`, `Resolution Agreement`. Deliberately not `corpusType`, which says which body of law a document belongs to: two documents in one corpus can be very different instruments. Omitted from the response when it has no value. - `documentSubtype` string, nullable: Finer instrument class where the publisher gives one. On presidential documents this separates an executive order from a proclamation, a memorandum or a notice (~90% populated there). Omitted from the response when it has no value. - `action` string, nullable: The Federal Register's own ACTION line, ~100% populated. Carries distinctions no other field makes: interim final rule, direct final rule, withdrawal, reopening of the comment period. Omitted from the response when it has no value. - `president` string, nullable: The president in office for this document, on Federal Register and presidential-document corpora spanning 1994 to present. Omitted from the response when it has no value. - `signingDate` string, nullable: When a presidential document was signed, as `YYYY-MM-DD`, which is routinely earlier than `publicationDate` and is the legally operative date. See `signingDateRaw`. Omitted from the response when it has no value. - `signingDateRaw` string, nullable: The signing date as the publisher writes it, present only when it differs from `signingDate`. - `executiveOrderNumber` string, nullable: The executive order number a lawyer cites the order by (`14179` for Executive Order 14179 of January 23, 2025). Set only on executive orders; the `citation` is the Federal Register page, not this. See `instrumentNumberSource` for where the value came from. Omitted from the response when it has no value. - `proclamationNumber` string, nullable: The proclamation number (`10886` for Proclamation 10886). Set only on proclamations. Memoranda, determinations and notices are not numbered in either series and carry null in both fields, never an invented number. Omitted from the response when it has no value. - `instrumentNumberSource` string, nullable: Provenance of `executiveOrderNumber` / `proclamationNumber`. `stored` is the number recorded when the document was ingested. `derived_from_text` is read at request time from the document's own header line (`Executive Order 14179 of January 23, 2025`), accepted only when that line opens the document and its date equals `signingDate`; it is null when the header is not in the text returned (for example a later chunk of a search hit), which means unknown, not unnumbered. Omitted from the response when it has no value. - `datesText` string, nullable: The verbatim DATES block from the Federal Register, ~98% populated. Worth reading alongside `frEffectiveOn`: a rule with staged or conditional effective dates has them here, and the single date flattens that away. Omitted from the response when it has no value. - `frVolume` integer, nullable: Federal Register volume, the `66` in `66 FR 64768`. Omitted from the response when it has no value. - `frStartPage` integer, nullable: First Federal Register page, the `64768` in `66 FR 64768`. Omitted from the response when it has no value. - `frEndPage` integer, nullable: Last Federal Register page. With `frStartPage` this gives the page RANGE, which `citation` cannot express because it carries only the first page. Omitted from the response when it has no value. - `wordCount` integer, nullable: Words in the full document, so a caller can size a fetch before paying for the body. Omitted from the response when it has no value. - `issuingAgency` string, nullable: The body that promulgated or issued this document: the state agency behind a regulation, the division behind an agency letter. Populated at 83.6-100% across the state-regulation corpora that carry it. Omitted from the response when it has no value. - `adoptingCitations` string[], nullable: Citations to the instrument that ADOPTED this rule: the state register notice, the Washington filing number, the adopting order. The rulemaking audit trail. Unified across four different payload spellings, so this is comparable across states in a way the underlying data is not. These are also the independent way to confirm a section when the publisher's own page cannot be read without a browser (see `externalUrl`): a Texas rule's `['50 TexReg 8285']` names the Texas Register issue and page that printed its adoption. Omitted from the response when it has no value. - `lawImplemented` string, nullable: The statute this rule IMPLEMENTS, as distinct from `statutoryAuthority`, which is the statute granting the rulemaking power. Florida populates both and they differ. Omitted from the response when it has no value. - `lastAmendedDate` string, nullable: Full date of the most recent amendment, as `YYYY-MM-DD`, where the publisher gives one. See `lastAmendedDateRaw` for the wording. Illinois and Colorado regulations carry their amendment provenance only here and in `amendmentNote`: neither state has a `history`, and Colorado has no `effectiveDate` either, so for Colorado this is the only date that exists. Omitted from the response when it has no value. - `lastAmendedDateRaw` string, nullable: The last-amended date as the publisher writes it, present only when it differs from `lastAmendedDate`, or null when it is not a date at all. - `amendmentNote` string, nullable: The publisher's amendment credit line where it is stored separately from `history`. Illinois and Colorado regulations, ~72% populated. Omitted from the response when it has no value. - `currencyYear` integer, nullable: Machine-readable counterpart to `currencyNote`, which is prose. 100% populated on the nine state-regulation corpora that carry a currency statement. Omitted from the response when it has no value. - `reviewDate` string, nullable: The date a rule must be re-adopted or it expires, where the state runs a sunset review. Ohio regulations, ~80% populated. Not an amendment date: it is in the future. Omitted from the response when it has no value. - `reviewDateRaw` string, nullable: The review date as the publisher writes it, present only when it differs from `reviewDate`, or null when it is not a date at all. - `originalEnactmentDate` string, nullable: When the section was FIRST enacted, as `YYYY-MM-DD`, ~72% populated on the US Code. Deliberately separate from `effectiveDate`: merging them would report an amended section as effective from its original year. On 35.7% of US Code points this is the only enactment date we hold. See `originalEnactmentDateRaw` for the publisher's wording. Omitted from the response when it has no value. - `originalEnactmentDateRaw` string, nullable: The enactment date as the publisher writes it, present only when it differs from `originalEnactmentDate`. The US Code prints `Aug. 14, 1935` where GovInfo statute compilations print `1935-08-14` for the same fact. - `releaseDate` string, nullable: When the document was released publicly, where that differs from when it was issued. NLRB advice memoranda are written years before release; measured, the two dates are never equal. Omitted from the response when it has no value. - `releaseDateRaw` string, nullable: The release date as the publisher writes it, present only when it differs from `releaseDate`, or null when it is not a date at all. - `documentNumber` string, nullable: The issuer's own document or case number, for exact lookup: an FCC DA number, an NLRB case-handling docket, a ruling number. On NLRB advice memoranda and FCC/HHS OCR documents this is not recoverable from `sectionNumber`. Omitted from the response when it has no value. - `caseName` string, nullable: The charged party or covered entity a document concerns. Only 27% equal to `sectionTitle` on HHS OCR, so it is not recoverable from the served text. Omitted from the response when it has no value. - `forum` string, nullable: For `corpusType=AGENCY_ADJUDICATION`, the KIND of proceeding that produced the document, in the publisher's own words. On CFPB enforcement actions this is `Administrative Proceeding` (the Bureau's own Office of Administrative Adjudication, under 12 C.F.R. Part 1081) or `Civil Action` (a suit the Bureau filed in a federal district court). One action can carry both, in which case they are joined with `; `. Null on every other corpus. Omitted from the response when it has no value. - `court` string, nullable: The body that heard the matter, where the publisher names one. Distinct from `forum`, which is the KIND of proceeding: `forum` has two values and is what you filter on, `court` has as many values as there are districts and is for display. Populated on every CFPB civil action and on the administrative proceedings the Bureau labels with its own adjudication office. Omitted from the response when it has no value. - `relatedDocuments` string[], nullable: The publisher's own labels for the filings whose text this record carries, in the order the publisher lists them. A CFPB enforcement action is ONE legal event published as two to seventeen PDFs and the unit we serve is the ACTION, not the filing: a consent order and the stipulation consenting to it are one record, because splitting them makes every search return two half-answers. This is what tells you which filings are inside the record you are holding. Only the operative instrument is mirrored under `pdfUrl`. Omitted from the response when it has no value. - `settlementAmount` string, nullable: The monetary penalty or settlement, as the agency prints it. 95.2% populated on HHS OCR resolution agreements, where it is the single most-asked fact of the corpus. Omitted from the response when it has no value. - `requesters` string[], nullable: Who asked for the determination or relief. On export-control commodity-jurisdiction determinations this is the applicant (100% populated); on no-action letters it determines who may rely on the relief. Omitted from the response when it has no value. - `program` string, nullable: The benefit or regulatory program a document governs, e.g. Old-Age and Survivors Insurance. 100% populated on Social Security rulings, where it is the primary axis a practitioner filters on. Omitted from the response when it has no value. - `languageCode` string, nullable: ISO code of the language the document is written in, present where a corpus is not wholly English. 86% of Puerto Rico insurance bulletins are Spanish (`es`). Omitted from the response when it has no value. - `volume` integer, nullable: Volume number for corpora organised in volumes, e.g. the USCIS Policy Manual, whose Volume is the top hierarchy level and had no served representation at all. Omitted from the response when it has no value. - `articleNumber` string, nullable: Article number. Article is the PRIMARY hierarchy level in state constitutions, where `chapter` and `part` are 0-6% populated, so without this those corpora served almost no structure. Omitted from the response when it has no value. - `articleName` string, nullable: Article title, the companion to `articleNumber`. Omitted from the response when it has no value. - `ruleSetCode` string, nullable: Stable machine key for the rule family, where `ruleSet` gives only the prose name. 100% populated on the court-rules states that have a rule set. Omitted from the response when it has no value. - `edition` string, nullable: The publisher's edition or year for this text. Omitted from the response when it has no value. - `relatedCitations` string[], nullable: Citations OUT of this document that are neither USC nor CFR: the state statutes a regulation implements, the Internal Revenue Code sections a ruling construes, other guidance it points at. `crossReferencesUsc` and `crossReferencesCfr` are 0% on several of these corpora, so this is the only outbound citation set they have. Omitted from the response when it has no value. - `supersessionActions` object, nullable: What this document does to EARLIER documents, keyed by the issuer's own verb: `modifies`, `obsoletes`, `amplifies`, `clarifies`, `rescinds`, each mapping to the documents affected. `supersedes` and `supersededBy` cover only the strongest verb. Without these a caller cannot tell a modified revenue procedure from an untouched one, nor see which memorandum rescinded which. Omitted from the response when it has no value. - `subtitle` string, nullable: Subtitle, where a jurisdiction puts a level between title and chapter. Maryland's regulations are organised Title > Subtitle > Chapter and are 100% populated; no other served field expressed that level. Deliberately not the same as `subchapter`, which sits below chapter. Omitted from the response when it has no value. - `subtitleName` string, nullable: Subtitle title, the companion to `subtitle`. Omitted from the response when it has no value. - `publisherKey` string, nullable: The publisher's own stable identifier for this document, where it issues one. On the US Code this is the OLRC's `usckey` (100% populated), which joins directly to the uscode.house.gov bulk XML; on Colorado regulations it is the state's rule id. Use it to reconcile our records against the publisher's without matching on citation strings. Omitted from the response when it has no value. - `versionId` string, nullable: The publisher's identifier for THIS VERSION of the document, where it versions them separately from the document itself. 100% populated on Colorado regulations, where it is the only version pointer that exists. Omitted from the response when it has no value. - `referencedShortTitles` string[], nullable: Popular names of acts this section REFERENCES, ~10% of the US Code. Distinct from `popularName`, which is the section's own. Omitted from the response when it has no value. - `subjectNumber` string, nullable: The publisher's numbered subject index entry, the companion to the term in `topics`. 100% populated on Social Security rulings. Omitted from the response when it has no value. - `audience` string, nullable: Who the document is addressed to or binds, where the issuer states it. 100% populated on the Montana insurance bulletins. Omitted from the response when it has no value. - `sourceCharStart` integer, nullable: Character offset where this text begins in the source document, for callers reconciling our extraction against the original PDF. Pairs with `sourcePageStart`. Omitted from the response when it has no value. - `sourceCharEnd` integer, nullable: Character offset where this text ends in the source document. Omitted from the response when it has no value. - `matchSegment` 'rule_text' | 'source_credit' | 'note', nullable, required: On a search hit in a federal rule, which part of the rule document the matched passage sits in: `rule_text`, `source_credit`, or `note` (an Advisory Committee Note). Null when unknown, and always null outside federal rules and on a section fetched by id. A label only, it never changes the ranking. - `matchNoteYear` integer, nullable, required: When `matchSegment` is `note`, the year named by the note heading the passage sits under (1993 for 'Notes of Advisory Committee on Rules, 1993 Amendment'). Null when the heading names no year or `matchSegment` is not `note`. - `alternateCitations` string[], nullable: Other official citation forms for THIS document, where a publisher prints more than one. Puerto Rico gives an L.P.R.A. cite, Arizona a long form, the IRS an Internal Revenue Bulletin cite, the Federal Reserve a paired Consumer Affairs number. Distinct from `relatedCitations`, which is what this document points AT. Use these when you need to match a citation a user typed in the form their jurisdiction actually publishes. Omitted from the response when it has no value. - `expirationDate` string, nullable: When this rule lapses unless re-adopted, as `YYYY-MM-DD`. Distinct from `reviewDate` (the review deadline) and from any amendment date: it is in the future and it ENDS the rule. See `expirationDateRaw` for the publisher's wording. Omitted from the response when it has no value. - `expirationDateRaw` string, nullable: The expiry date as the publisher writes it, present only when it differs from `expirationDate`. State regulators print this as `1/1/2028` and `03-01-2029` as well as ISO. - `committeeNote` string, nullable: Advisory-committee note on a procedural rule: the standard interpretive gloss courts read alongside the rule text. Deliberately separate from `amendmentNote`, which records when the rule changed rather than what it means. Omitted from the response when it has no value. - `sourcePageStart` integer, nullable: First page in the official PDF this text was extracted from, for a pinpoint print citation. 100% populated on the Federal Rules. Omitted from the response when it has no value. - `sourcePageEnd` integer, nullable: Last page in the official PDF; companion to `sourcePageStart`. Omitted from the response when it has no value. - `displayLabel` string, nullable: The publisher's own short label for this section, e.g. `Cal. BPC § 655.2` or `MPEP § 2165.03`. Populated on essentially every document we hold. Usually equal to `citationShort`, but not always: on the Federal Communications Commission, NLRB, HHS OCR and BIS corpora the two differ on every document, and there `displayLabel` is the form the publisher itself prints. Omitted from the response when it has no value. - `publicationDate` string, nullable: The date this document was published by its source. For Federal Register documents this is the FR publication date, the primary citation and sort key, populated on 100% of rules and proposed rules. Distinct from `effectiveDate` (when it takes legal effect) and from `issueDate` (when the issuing body dated it). A rule is routinely published before it is effective. Omitted from the response when it has no value. - `publicationDateRaw` string, nullable: The publication date as the publisher writes it, present only when it differs from `publicationDate`, or null when it is not a date at all. - `publicLawCites` object[], nullable: Structured Statutes at Large citations parsed out of the source credit, populated on ~72% of the US Code. Each entry carries `statVolume`, `statPage`, `type` and a `display` string. `publicLaws` gives the bare `Pub. L.` list and `sourceCredit` the raw prose; this is the same information already parsed, so a caller can link to the Statutes at Large without re-parsing the credit line. Omitted from the response when it has no value. - `topLevelTitle` string, nullable: The outermost division this document sits under, where the corpus has one that `titleNumber`/`chapter`/`part` do not already express. Examples: `Title 9: Criminal` for the DOJ Justice Manual, `Volume 1 - General Policies and Procedures` for the USCIS Policy Manual. Null for flat corpora, where one document is the whole unit. Omitted from the response when it has no value. - `externalUrl` string, nullable, required: The publisher's own page for this section, exactly as recorded at ingest: uscode.house.gov, ecfr.gov, a state legislature or a state register. Null when the publisher issues no per-section link, or when the link is withheld. Prefer `sourceUrl`, which is this link when present and otherwise the best official alternative. Some official publishers serve their code only through a JavaScript application, so the link renders in a browser but returns an empty page shell to a plain HTTP client. Texas is the main case: the Secretary of State publishes the Texas Administrative Code only on its Appian portal (texas-sos.appianportalsgov.com). The link is still the correct citation. To check a section without a browser, use `adoptingCitations` (for Texas, the `NN TexReg PPPP` register citations that adopted and amended it) and read the text we captured at `textUrl`. - `sourceUrl` string, nullable, required: Where the government published this text: the link to cite and to verify against. The same value `/us/statutes/section/{actId}/body` returns as `sourceUrl`, on every search result, section record and batch item. It is `externalUrl` when the publisher issued a per-section link, and otherwise falls back to the govinfo.gov page, then the state's own page, then our archived copy of the publisher's page. Null when we hold no publishable link: only official government links are served here. - `sourceUrlNote` string, nullable, required: Says why `sourceUrl` is null. Either we serve no link for this section on purpose and it is cited by `citation` alone, or the publisher issues it only inside a larger file (an archive, spreadsheet or whole volume) that is not a page of the section, or no source link is recorded for it at all. Null when `sourceUrl` is set. - `count` integer: How many results came back in THIS response, i.e. the length of `results`. It is not a total match count: the API ranks a bounded set of candidates rather than scoring the whole corpus, so no such total exists. Use `hasMore` to decide whether to ask for another page. With `matchType: "boolean"` the total is `totalMatches`. - `total` integer: DEPRECATED alias for `count`, kept for backward compatibility. The name reads as a corpus-wide match total, which it never was. Use `count` instead. - `offset` integer: The offset applied to this page. - `hasMore` boolean: Whether more results exist beyond this page. For `any`, `all` and `phrase` this is relative to a bounded ranking pool of roughly 60 to 90 sections, so false means the pool is exhausted, not that nothing else in the corpus matches. Use `matchType: "boolean"` and follow `nextOffset` to page through every match. - `changedSectionCount` integer, nullable: Only present when `changedSince` is set: how many sections changed in that window, before ranking. Compare it against `count`. `changedSince` is a filter on a RANKED search, so a window holding more sections than one query can return is normal and the page you get is the most relevant slice of it, not all of it. When this number is larger than you can page to, the filter is a trigger rather than an inventory: subscribe to the board and poll `GET /watches/{id}/changes`, which is complete and costs no credits. - `rankingDegraded` boolean: True when the relevance model (a cross-encoder) was unavailable and the results are in hybrid-retrieval order instead. The sections are still real matches for the query, but the ordering is coarser and `relevanceScore` is a retrieval score rather than a 0-1 relevance, so do not threshold on it. Such a ranking is never cached: retrying shortly returns the fully ranked result once the model recovers. - `noGoodMatch` boolean, nullable: True when nothing in the corpus looks on point for this query. It says nothing about whether the top result is the right section; check its citation and jurisdiction. False when the top result clears the relevance bar, or when the query is a citation or a section number that matched exactly. Null when `rankingDegraded` is true, because the bar is on the relevance model's scale. The same on every page of a query. - `matchQuality` 'exact' | 'strong' | 'moderate' | 'weak' | 'none', nullable: How strongly the evidence says result #1 answers the query. exact: a citation or section-number match. strong: the top result was correct about 94% of the time in our measurements (about 91% on questions whose answer is a statute or regulation). moderate: about 67%. weak: about 35%. none: nothing on point (same as noGoodMatch). Measured on our labelled evaluation set; tiers may be re-cut as the index changes, so treat unknown values as moderate. Null when `rankingDegraded` is true. The same on every page of a query. - `citationOutsideFilters` CitationOutsideFilters: A citation that names a real section the caller's own filters exclude. Both `/search` and `/resolve` treat a filter as a promise: a citation outside it is not forced into the results. This says so, instead of leaving a caller to read an unrelated top hit (or `resolved: false`) as "no such section". - `actId` string, required: The section the citation names. Pass it to `/section/{actId}` to read it. - `citation` string, nullable: That section's citation, as it appears in results. - `title` string, nullable: That section's heading. - `state` string, nullable: That section's jurisdiction: `federal` or a two-letter state code. - `corpusType` string, nullable: That section's corpus, e.g. `USC`, `CFR`, `STATE`. - `excludedBy` string[]: The request filters that exclude the section, by their public names (`state`, `corpusType`, `code`, `article`, `titleNumber`, `chapter`, `part`, `yearFrom`, `yearTo`). Empty when the exclusion comes from a condition only the index can attribute (`excludeRepealed`, `actStatus`, `source`, `changedSince` and the Federal Register facets): then any of the filters you set may be responsible. - `citationMissReason` CitationMissReason: The same finding as one block, for a response that is not itself a citation verdict. `POST /us/statutes/search` carries it as `citationMissReason`, beside `citationOutsideFilters`: the query was a citation, the resolver missed, and the ranked results are an ordinary search. - `missReason` 'not_held' | 'former_law' | 'ambiguous_jurisdiction' | 'malformed' | 'out_of_scope_corpus' | 'container_not_supported' | 'index_warming' | 'lookup_failed' | 'miss_reason_unavailable', required: Present only when `resolved` is false and none of `citationOutsideFilters` / `sessionLaw` already explains it. WHY the citation did not resolve: `ambiguous_jurisdiction` (the form is one several jurisdictions print, or names none, and no `state` was given: pass `state`; `candidates` lists the held sections it could mean when we can name them, and never picks one), `out_of_scope_corpus` (it names a body of law this route does not serve; `missReasonHint` says which and where to look), `former_law` (it names a repealed, renumbered or retired compilation we do not serve as current law; `missReasonHint` names the successor where one is known), `malformed` (no parser reads it: a docket or database token, a case or treatise citation, a string with no section number, or a subdivision or edition year with no section before it), `container_not_supported` (it cites a chapter, article, title or part, not a section; this route resolves sections, and answers a container only in the forms `matchLevel: container` lists: browse it with `GET /us/statutes/divisions`, or cite a section inside it), `not_held` (it reads as a citation to a jurisdiction and corpus we serve, and that corpus does not hold the section), `index_warming` (batch items only: the code this citation names was still being read when the call arrived, so there is NO verdict about the citation; the item is not billed, and sending it again in a few seconds answers it), `lookup_failed` (batch items only: the citation resolved, but WE failed to load or serialize its section, so this says nothing about whether the section exists; the item is refunded and counted in the response's `failedCount`, and retrying it answers it). `miss_reason_unavailable` (the check that explains a miss timed out or failed on our side, so this response carries NO explanation: it says nothing about why the citation did not resolve, and resending it usually answers; the citation's own verdict, unresolved, is unchanged and charged as any miss is). A miss is still charged, because the verdict is the product, except `index_warming` and `lookup_failed`, which are not verdicts and are never charged; the reason itself adds no charge. Absent on a resolved citation. - `missReasonHint` string, nullable: Present with `missReason`. One sentence on what to try next. Prose for a human or an agent; do not parse it. Omitted from the response when it has no value. - `candidates` MissReasonCandidate[], nullable: Present only with `missReason: ambiguous_jurisdiction`, and only when we can name the held sections the citation could mean (an acronym two states print, such as `CCR`). At most 10 entries. Pass the right one's `state` to `GET /us/statutes/resolve` to resolve it. Never a pick: when several are listed, none is the answer. - `state` string, required: The jurisdiction to pass as `state` to resolve this one. - `actId` string, required: The section's id. - `citation` string, nullable: Its own citation, as it appears in results. - `subsection` string, nullable: The pinpoint the citation carried, if any. - `parsedQuery` string, nullable: Present only with `matchType: "boolean"`: the expression as it was read, in canonical form with explicit operators and grouping, e.g. `(work OR employment) AND retaliation`. Paste it back to run the same search. - `queryWarnings` string[], nullable: Present only with `matchType: "boolean"` when the expression is valid but may not mean what was intended: AND and OR combined without parentheses (services disagree on which binds first), lowercase and / or / not (searched as words), or an ignored ^ boost. The search ran as `parsedQuery` shows; nothing was changed. - `totalMatches` integer, nullable: Present only with `matchType: "boolean"`: how many sections satisfy the expression within your filters, across ALL pages, not just this one. Read it with `totalMatchesExact`. Absent when it could not be counted in time. The same on every page of a query. - `totalMatchesExact` boolean, nullable: Present with `totalMatches`. True: it is the exact number of matching sections (a section the corpus holds under two ids, such as a Federal Rule kept in two collections, counts twice and is served once). False: it is an UPPER BOUND, because the expression uses an operator the count cannot judge exactly (phrases, `/s`, `/p`, proximity, `atleastN`, wildcards inside proximity) or a filter the count does not apply (anything beyond `corpusType`, `state`, `actStatus` and `excludeRepealed`); every served row still satisfies the expression. Omitted from the response when it has no value. - `relevanceRankedCount` integer, nullable: Present only with `matchType: "boolean"`: how many leading results (at most 120) are ordered by the relevance model. Results after them continue in keyword (BM25) order and repeat the last ranked `relevanceScore`, so every match can be paged to without being re-scored. - `nextOffset` integer, nullable: Present only with `matchType` `boolean`, `all` or `phrase` while `hasMore` is true: the `offset` to send for the next page. Usually `offset` + `limit`. Past the relevance-ranked results a page can hold fewer rows than `limit` (candidates outside your filters, or failing the expression on full-text verification, are left out), and when verification runs out of time the page stops early and `nextOffset` resumes exactly where it stopped. Follow it rather than computing the offset. For `any` the field is absent: while `hasMore` is true, request the next page with `offset` + `limit`. - `queryHint` string, nullable: Present only with `matchType: "any"` when the query is written in Boolean syntax (an UPPERCASE AND/OR/NOT between words, a proximity connector such as `/s` or `/5`, or `atleastN(`). The search was not run as Boolean: retry with `matchType: "boolean"` to apply the operators. - `pinpoints` object, nullable: Present only when the request set `includePinpoint: true`. Names the subsection each hit matched, keyed by the hit's `actId`: a hit for `30 mph urban district speed limit` reads `625 ILCS 5/11-601(c)(1)`. One entry per returned result, so a result with no entry here was not looked at (see `pinpointNote`). Read `located` first. When it is true, `pinpoint` and `citation` name the unit, `text` is its own text and `leadIn` the text of each ancestor it completes, and `charStart` / `charEnd` index into the `plain` text of `GET /us/statutes/section/{actId}/body` (see `structure.textSha256`). When it is false, `reason` and `note` say why no subsection is named; the section itself is still a real match. A subsection is named only when the words of your query point at it: a question put in other words than the law's, or a query that fits several unrelated subsections equally, gets no pinpoint rather than a guess. `matchedTerms` shows which of your words the unit carries. No extra charge. - `pinpointNote` string, nullable: Present only when the request set `includePinpoint: true` and no pinpoints were looked up for this page, with the reason: the relevance model was unavailable (`rankingDegraded`), the candidate pool was incomplete (so the results are a coarser answer), or the pinpoint step itself failed (`lookup_failed`). Retry shortly for the full one. The pinpoint lookup is never charged on its own; a page served with `rankingDegraded: true` is refunded whether or not pinpoints were asked for (see `notes` and `creditsConsumed`), and any other page is charged as an ordinary search. - `droppedCount` integer, nullable: Present only when this page is SHORT because that many ranked hits could not be loaded or serialized on our side and were left out: `count` is then smaller than the page the ranking chose. It is a fault, not a filter, and says nothing about whether those sections exist; repeat the call to get them. Absent on a complete page. - `bodyNote` string, nullable: Present only when `includeBody: true` was set and the bodies were withheld because the balance could not cover them (each row says `bodyNote: insufficient_credits`). The ranking was served and billed as usual; no body was charged. - `rankingPartial` boolean: True when part of the candidate pool could not be built (a retrieval leg failed or the query embedding was unavailable) or a citation in the query could not be checked against your filters. The results are real matches but a coarser answer than a complete pool would give. Such a ranking is not cached, so repeating the call may return the full one. Absent on a complete page. - `notes` string[], nullable: Plain-language notes about THIS page, present only when there is something to say: why an empty page was not charged and which filters emptied it, that `noGoodMatch` is charged, that a `changedSince` window of zero sections is not proof that nothing changed for a corpus without a captured change log, or that filters applied after the Boolean candidate index left the page shorter than `limit`. - `query` string: The search query used. - `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, after any refund. Failed work bills 0 and batch endpoints charge per item returned. ## Other responses - `401`: Missing, invalid or revoked API key. - `402`: Insufficient credits (`insufficient_credits`, never retry). `creditsRequired` and `creditsAvailable` say how short you are when known; top up, then repeat the call. - `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`: Invalid request body (e.g. query too short, limit over 50, bad corpusType). `idempotency_key_reused`: the `Idempotency-Key` was already used with a different request. - `429`: Rate limit exceeded. - `500`: Internal error (`internal_error`, retryable). Any credits charged for the call are refunded; retry with backoff and quote `requestId` to support if it persists. - `503`: A backend this search needs is temporarily unavailable, or the search ran past its overall time budget. Not charged: retry with backoff. ## Changes - **2026-11-07** `340c0d24d0b6`: 1 breaking, 2 warning, 105 info - the `excerptChars` request property's max was decreased to `600.00` - added the new `miss_reason_unavailable` enum value to the `citationMissReason/anyOf[subschema #1: CitationMissReason]/missReason` response property for the response status `200` - added the new `response_size_cap` enum value to the `results/items/bodyNote/anyOf[subschema #1]/` response property for the response status `200` - added the non-success response with the status `500` - …104 more [Operation history](https://skmtc.dev/vaquill/apis/vaquill-developer-api/changes/api/v1/us/statutes/search/post.md) --- [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/340c0d24d0b6?raw)