> ## Documentation Index > Fetch the complete documentation index at: https://vaquill.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Find the citations in a text and resolve each > Read a block of text (a brief, a memo, a statute-heavy email, a model's answer) and return every distinct non-case legal citation in it, each resolved to the section it names. The text-in counterpart of `POST /us/statutes/resolve`: one call instead of extracting the citations yourself and sending them in batches of 50. Extraction reads statutes, regulations, court rules, constitutions and registers, in federal and state form (`42 U.S.C. § 1983(b)`, `Cal. Civ. Code § 1942`, `Fed. R. Civ. P. 12`, `8 CCR 1206-2`, `N.Y. Const. art. I, § 8`). It does not extract case citations. It is measured, not perfect: about 0.92 to 0.98 precision and 0.80 to 0.85 recall on unseen opinion text, so a citation can be missed and a non-citation can be read as one; `resolved` is what we verified. `extractorVersion` is the extractor's version: the same text can yield different citations when it changes. **Dedupe.** A citation is one row however many times it appears (`mentions` counts them, the first pinpoint is kept), and is resolved once. `42 U.S.C. § 1983` and `42 U.S.C.A. § 1983` are two rows, because they are two strings a reader might want checked; both carry the same `actId`. **Cost**: 2 credits per DISTINCT citation sent to the resolver, the same as `POST /us/statutes/resolve`, so pasting a document costs what pasting its citations one by one costs. The extraction itself is free: `resolve: false` returns the citations found and charges nothing. An unresolved citation is charged (the verdict is the product); a session-law citation (`skipped: session_law`, read it under `/us/session-laws`) is not resolved here and not charged; a citation we fail to process is refunded one by one, and an outage that takes half of them or more answers 503 and refunds the call. The charge is taken after extraction and before any lookup, so `creditsConsumed` is known up front. One call resolves at most 200 distinct citations, so one click is at most 400 credits; `truncated: true` says more were found and only the listed ones were charged. **Limits.** `text` is at most 200,000 characters (a 422, never a truncation) and must be text. A key may send 5,000 resolutions a day through this route; past that the call answers 429 with `Retry-After` and nothing is charged. The text is never stored. **Unresolved rows** carry `missReason`, `candidates` and `missReasonHint`, the same finding `GET /us/statutes/resolve` gives (no extra charge). Pass `state` (the document's jurisdiction) so a citation that names none, such as `Civil Rule 56.1`, is checked against the right one. **Related**: `POST /us/statutes/resolve` for citations you already hold; `GET /us/statutes/section/{actId}` to read a resolved section. ## OpenAPI ````yaml https://api.vaquill.ai/external/openapi.json post /api/v1/us/statutes/extract-citations openapi: 3.1.0 info: title: Vaquill Developer API description: >- Public API for legal statutes and legislation. **Authentication**: Pass your API key as `Authorization: Bearer vq_key_...` (preferred) or in the `X-API-Key` header. The `api_key` query parameter also works where a header cannot be set, but a URL ends up in logs and browser history. Sending two different keys in one request is rejected with a 401. **Credits**: Each call costs API credits. See `GET /api/v1/api-credits/pricing` for the full pricing matrix. ## Jurisdictions | Jurisdiction | Coverage | `countryCode` | |---|---|---| | **United States** | USC and the Statutes at Large, the CFR and its annual editions, all 56 state and territory statutory codes (50 states, DC and five territories), state administrative regulations, court rules, federal and state constitutions, federal agency guidance and adjudications, the Federal Register, the Sentencing Guidelines and US tax treaties. | `US` | See the full [Coverage page](https://www.vaquill.ai/docs/api-guide/coverage) for the jurisdiction-by-jurisdiction breakdown, or call `/us/statutes/coverage` for live counts. Coverage is per (jurisdiction, corpusType) pair, so treat that endpoint as the authoritative list rather than this summary. ## Endpoints - **US Statutes**: Search and retrieve any of the corpora above with full text, resolve a citation to its exact section, browse the statutory hierarchy, read a section as it stood on a past date, and follow its change history, cross-references and defined terms - **Board Watches**: Subscribe to a corpus source and get a webhook or email when it refreshes with real changes (free, API key required) - **Pricing**: Credit costs per endpoint (no auth required) ## Rate limits Limits are enforced per API key and scale with your plan. A `429` response includes a `Retry-After` header. | Plan | Per minute | Per hour | Per day | |---|---|---|---| | Vaquill API Pro | 60 | 1,000 | 2,000 | | Vaquill API Business | 150 | 2,500 | 10,000 | For full documentation, visit the [API Reference](https://www.vaquill.ai/docs/api-reference/). version: 1.0.0 contact: name: Vaquill API Support url: https://www.vaquill.ai email: support@vaquill.ai license: name: Proprietary url: https://www.vaquill.ai/terms termsOfService: https://www.vaquill.ai/terms servers: - url: https://api.vaquill.ai description: Production security: - ApiKeyAuth: [] - ApiKeyHeader: [] - ApiKeyQuery: [] tags: - name: US Statutes description: >- Search and retrieve US primary law. Covers the United States Code and the Statutes at Large, the Code of Federal Regulations and its annual editions, state statutory codes and administrative regulations, federal and state constitutions, court rules, Federal Register rules and Presidential documents, federal and state agency guidance, agency adjudications, state Attorney General opinions, the Sentencing Guidelines and US tax treaties. Scope a search with the `corpusType` filter, and call `/us/statutes/coverage` for the live jurisdiction-by-corpusType list. - **Search**: Search across all USC, CFR, state, and regulatory sections - **Section**: Get metadata, citation, hierarchy, and source links for a specific section - **Body**: Get the full text of a section - **Enactments**: Which state session laws a publisher's own tables list against a section (supported jurisdictions only, never a complete history) - name: US Session Laws description: >- State session laws: the acts of each legislature as they were enacted, chapter by chapter, before they are folded into a code. A session law is what the governor signs. It carries the act's own text, including the language it strikes and inserts, its approval and effective dates, and, where the publisher prints one, the code sections it changes. That makes it the source for "which act changed this section, and when did it take effect". Every act has a permanent `sessionLawId` (for example `SSL_MN_2025R_G_Y2025_C1`, Minnesota Laws 2025, regular session, chapter 1) whether or not we hold its text, and a citation or bill number such as `S.F.No. 1552` is accepted where an id goes. v1 serves STATE acts only. Federal session laws (the Statutes at Large, `SAL_` ids) are served by `/us/statutes/section`, and `/us/statutes/resolve` points a session-law citation here. **Start here**: check `/us/statutes/coverage` (free) for what we hold per state: each jurisdiction's `sessionLaws` block lists its sessions, which are complete or only partly collected, and the `series` and `instrumentTypes` that exist. Then **List** a session or a date range to get ids, **Get** one act for its record, then **Body** for its text. A law missing from a partly collected session is a free 404 (`session_not_fully_collected`), not proof it does not exist. - **List**: everything enacted in a state's session, approved in a window, or taking effect on a date - **Get**: one act by id or by citation; dates (`effectiveDates` is always a list), sources and the code sections it affects - **Body**: the act's text as printed, paged by cursor, with amendatory markup preserved where the publisher printed it - **Batch**: up to 50 ids or citations in one call, the same record as Get, billed per law served, with every miss listed and its reason - **Changes**: a sync feed of the registry over an integer cursor (`sinceId`): what began to be served, was corrected, withdrawn or merged The reverse link, from a code section to the acts a publisher's own tables list against it, is `GET /us/statutes/section/{actId}/enactments`. - name: Board Watches description: >- Law-change alerts. Subscribe to a **board** (a tracked corpus source, identified by `corpusType` plus an optional `state`) and get a webhook or email whenever it refreshes with real changes, naming the exact sections that changed. Fetch old-vs-new text for any amended section via the change diff. Boards refresh on their own existing cadence; watching one does not change how often it refreshes. Every endpoint here is **free**: authenticated by API key and rate-limited, but not credit-metered. See the [Law Change Alerts guide](https://www.vaquill.ai/docs/api-guide/alerts) for the full walkthrough. - name: Pricing description: >- Credit pricing and conversion rates. No authentication required. 1 credit = $0.01 USD. - name: Credits description: >- Your own credit balance: what is spendable right now, where it came from, and what is about to expire. Free and never charged, so it is safe to poll for low-balance alerting or to pre-flight a batch job. externalDocs: description: Full API Reference url: https://www.vaquill.ai/docs/api-reference/ paths: /api/v1/us/statutes/extract-citations: post: tags: - US Statutes summary: Find the citations in a text and resolve each description: >- Read a block of text (a brief, a memo, a statute-heavy email, a model's answer) and return every distinct non-case legal citation in it, each resolved to the section it names. The text-in counterpart of `POST /us/statutes/resolve`: one call instead of extracting the citations yourself and sending them in batches of 50. Extraction reads statutes, regulations, court rules, constitutions and registers, in federal and state form (`42 U.S.C. § 1983(b)`, `Cal. Civ. Code § 1942`, `Fed. R. Civ. P. 12`, `8 CCR 1206-2`, `N.Y. Const. art. I, § 8`). It does not extract case citations. It is measured, not perfect: about 0.92 to 0.98 precision and 0.80 to 0.85 recall on unseen opinion text, so a citation can be missed and a non-citation can be read as one; `resolved` is what we verified. `extractorVersion` is the extractor's version: the same text can yield different citations when it changes. **Dedupe.** A citation is one row however many times it appears (`mentions` counts them, the first pinpoint is kept), and is resolved once. `42 U.S.C. § 1983` and `42 U.S.C.A. § 1983` are two rows, because they are two strings a reader might want checked; both carry the same `actId`. **Cost**: 2 credits per DISTINCT citation sent to the resolver, the same as `POST /us/statutes/resolve`, so pasting a document costs what pasting its citations one by one costs. The extraction itself is free: `resolve: false` returns the citations found and charges nothing. An unresolved citation is charged (the verdict is the product); a session-law citation (`skipped: session_law`, read it under `/us/session-laws`) is not resolved here and not charged; a citation we fail to process is refunded one by one, and an outage that takes half of them or more answers 503 and refunds the call. The charge is taken after extraction and before any lookup, so `creditsConsumed` is known up front. One call resolves at most 200 distinct citations, so one click is at most 400 credits; `truncated: true` says more were found and only the listed ones were charged. **Limits.** `text` is at most 200,000 characters (a 422, never a truncation) and must be text. A key may send 5,000 resolutions a day through this route; past that the call answers 429 with `Retry-After` and nothing is charged. The text is never stored. **Unresolved rows** carry `missReason`, `candidates` and `missReasonHint`, the same finding `GET /us/statutes/resolve` gives (no extra charge). Pass `state` (the document's jurisdiction) so a citation that names none, such as `Civil Rule 56.1`, is checked against the right one. **Related**: `POST /us/statutes/resolve` for citations you already hold; `GET /us/statutes/section/{actId}` to read a resolved section. operationId: extract_statute_citations requestBody: content: application/json: schema: $ref: '#/components/schemas/ExtractCitationsRequest' required: true responses: '200': description: >- The distinct citations found, each resolved unless `resolve` is false. content: application/json: schema: $ref: '#/components/schemas/ExtractCitationsResponse' example: citations: - citation: 42 U.S.C. § 1983 raw: 42 U.S.C. § 1983(b) type: Statute subtype: usc jurisdiction: US jurisdictionSource: cite pinpoint: (b) mentions: 2 resolved: true actId: USC_T42_C21_S1983 subsection: b - citation: Cal. Civ. Code § 99999 raw: Cal. Civ. Code § 99999 type: Statute subtype: state_statute jurisdiction: CA jurisdictionSource: cite pinpoint: '' mentions: 1 resolved: false missReason: not_held missReasonHint: >- This reads as a statute citation to CA, and we do not hold that section. Check the number, or find the provision by topic with `POST /us/statutes/search`. counts: found: 2 resolved: 1 unresolved: 1 skipped: 0 truncated: false textChars: 812 extractorVersion: 0.6.0 creditsConsumed: 4 processingTimeMs: 412 '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '402': description: Insufficient credits for the citations found. Nothing was resolved. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '422': description: >- `text` is empty, over the character limit, not text, or `state` is unknown. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '429': description: >- Rate limit exceeded, or this key's daily resolution allowance is spent (`Retry-After` says when it resets). Nothing was charged. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '503': description: >- The statutes corpus is temporarily unavailable. The charge is refunded. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' components: schemas: ExtractCitationsRequest: properties: text: type: string maxLength: 200000 minLength: 1 title: Text description: >- The text to read, 1 to 200,000 characters (a brief is about 30,000). Longer is a 422, never a silent truncation: a partial list reported as the whole is a wrong answer. Plain text; a body that is mostly binary is a 422. examples: - >- Plaintiff sued under 42 U.S.C. § 1983(b). See also Cal. Civ. Code § 1942 and 42 U.S.C. § 1983. state: anyOf: - type: string enum: - 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 - type: 'null' title: State description: >- The jurisdiction of the DOCUMENT as a two-letter state code (the forum of a filing, the governing state of a matter). It labels and scopes a citation that names no jurisdiction of its own (`Civil Rule 56.1`, `Gov. Code § 12940`); a citation that names a jurisdiction is always checked against that one, whatever this says. examples: - ca resolve: type: boolean title: Resolve description: >- Resolve each distinct citation to its section (priced per distinct citation, see the endpoint's Cost). `false` returns the extraction alone, which is free. default: true examples: - true includeUnresolved: type: boolean title: Includeunresolved description: >- `false` drops rows that did not resolve from `citations`. The `counts` and the charge are unchanged: an unresolved citation is a verdict that was paid for. default: true examples: - true additionalProperties: false type: object required: - text title: ExtractCitationsRequest example: resolve: true state: ca text: >- Plaintiff sued under 42 U.S.C. § 1983(b). See also Cal. Civ. Code § 1942 and 42 U.S.C. § 1983. ExtractCitationsResponse: properties: citations: items: $ref: '#/components/schemas/ExtractedCitationRow' type: array title: Citations description: The distinct citations, in order of first appearance. counts: $ref: '#/components/schemas/ExtractCitationsCounts' truncated: type: boolean title: Truncated description: >- True when more than 200 distinct citations were found and `citations` holds the first of them. `counts.found` still reports the number found, and only the ones listed were resolved and charged. default: false textChars: type: integer title: Textchars description: Characters of `text` read. extractorVersion: type: string title: Extractorversion description: >- The extractor's version. The same text can yield different citations when it changes, so cache extractions by text AND this value. examples: - 0.6.0 creditsConsumed: type: number title: Creditsconsumed description: Credits actually charged. 0 when `resolve` is false. default: 0 examples: - 6 processingTimeMs: type: number title: Processingtimems description: Server-side time for this request in milliseconds. Not billed on. default: 0 examples: - 412 type: object required: - counts - textChars - extractorVersion title: ExtractCitationsResponse ApiDetailError: properties: detail: type: string title: Detail description: >- Human-readable reason, safe to surface to an end user. Branch on the HTTP status rather than on this string: the wording is not part of the contract and may be reworded, but 401 (bad key), 402 (out of credits), 403 (missing scope), 404 (no such resource) and 429 (rate limited) are stable. examples: - Insufficient API credits. errors: anyOf: - items: $ref: '#/components/schemas/ApiFieldError' type: array - type: 'null' title: Errors description: 'Present on 422 only: every field that failed validation.' type: object required: - detail title: ApiDetailError description: >- Error envelope the API actually returns. Every error (400/401/402/403/404/405/422/429/5xx) carries a `detail` string, e.g. `{"detail": "Insufficient API credits."}`, on every mount of the API. A 422 adds `errors`, one entry per rejected field. Some 404s add endpoint-specific diagnosis beside `detail` (the statutes section routes add `actId`, `reason` and `didYouMean`); treat unknown keys as optional. ExtractedCitationRow: properties: citation: type: string title: Citation description: >- The citation, normalised. Pass it to `GET /us/statutes/resolve` to re-check. examples: - 42 U.S.C. § 1983 raw: type: string title: Raw description: The citation as it first appeared in your text, with its pinpoint. examples: - 42 U.S.C. § 1983(b) type: type: string title: Type description: >- `Statute`, `Regulation`, `Court Rule`, `Constitution`, `Admin. Register`, `Session Law` or `Other`. A coarse label read from the string; it can be wrong, and `resolved` is what we verified. examples: - Statute subtype: type: string title: Subtype description: >- A finer label: `usc`, `cfr`, `state_statute`, `state_rule`, `local_rule`, ... examples: - usc jurisdiction: anyOf: - type: string - type: 'null' title: Jurisdiction description: '`US` or a two-letter state code, when one could be read.' examples: - US jurisdictionSource: anyOf: - type: string enum: - cite - court - type: 'null' title: Jurisdictionsource description: >- `cite` when the citation names its jurisdiction itself; `court` when it was inferred from your `state`. Null when unknown. examples: - cite pinpoint: type: string title: Pinpoint description: The pinpoint of the first mention (`(b)`), empty when it had none. default: '' examples: - (b) mentions: type: integer title: Mentions description: >- How many times the citation appears in the text (one row, however many). default: 1 examples: - 2 resolved: type: boolean title: Resolved description: >- True when the citation resolved to a section. False when it did not, when `resolve` was false, or when it was `skipped`. actId: anyOf: - type: string - type: 'null' title: Actid description: >- The section it resolved to. Read it at `/us/statutes/section/{actId}`. examples: - USC_T42_C21_S1983 subsection: anyOf: - type: string - type: 'null' title: Subsection description: The pinpoint the resolver echoed, as on `/resolve`. examples: - b matchLevel: anyOf: - type: string enum: - container - multiple - repaired - register_reference - type: 'null' title: Matchlevel description: >- Present only when `section` is NOT the exact unit you cited. `container`: you cited a chapter, series, article, part or amendment, and `section` is the FIRST section inside it (see `container` for how many there are and what they are). `multiple`: you cited several sections (`§§ 8, 10`, `§§ 1983-1985`) and `section` is the first of them (see `citedSections`), or your citation fits more than one held section (`D.C.COLO.LR 7.1` is both Local Civil and Local Criminal Rule 7.1) and every candidate is listed in `container`. `repaired`: the code name you wrote is a recognised miscite and `section` is the one it names (see `repair`); or (`repair.kind: prior_edition`) the text you cited has been replaced by a current one, and `section` is NOT the text you cited: a C.F.R. or U.S.C. section the current code no longer holds, answered with the MOST RECENT historical annual edition we hold, or a superseded rule set whose rule numbers were kept, answered with the current rule (`Tex. R. Civ. Evid. 803` is answered by `Tex. R. Evid. 803`); `repair.interpretedAs` names what was served and why, and `repair.alternatives` lists the other held editions, if any; or (`repair.kind: former_law`, `former_number`) you cited a FORMER section number, recodified or renumbered since, and `section` is the successor the state's own disposition table or history line names, never the former text (a former section split into several answers `multiple`, every successor in `citedSections`). or (`repair.kind: code_name_inferred`) your citation named no code (`CODE ANN. § 73.001`, `Code 4121-3-34`) and `section` is the only one in the state that carries that number, so the code was inferred from the number and not read from your citation; `register_reference`: you cited a state register page, and `section` is a rule whose history cites it (see `registerReference`). `resolved` keeps its meaning (a section was returned) and is true at every level; read `matchLevel` to tell an exact section from a first-of-several. Absent for an exact match. examples: - container missReason: anyOf: - type: string enum: - not_held - former_law - ambiguous_jurisdiction - malformed - out_of_scope_corpus - type: 'null' title: Missreason description: >- 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), `not_held` (it reads as a citation to a jurisdiction and corpus we serve, and that corpus does not hold the section). A miss is still charged, because the verdict is the product; the reason adds no charge. Absent on a resolved citation. examples: - ambiguous_jurisdiction candidates: anyOf: - items: $ref: '#/components/schemas/MissReasonCandidate' type: array - type: 'null' title: Candidates description: >- 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. missReasonHint: anyOf: - type: string - type: 'null' title: Missreasonhint description: >- Present with `missReason`. One sentence on what to try next. Prose for a human or an agent; do not parse it. resolvedWithState: anyOf: - type: string - type: 'null' title: Resolvedwithstate description: >- The state scope that produced the answer when the unscoped resolve missed: the state the citation names, else your `state`. Null when it resolved as written. examples: - null skipped: anyOf: - type: string enum: - session_law - error - type: 'null' title: Skipped description: >- Why no resolution was attempted or it failed: `session_law` (an act as enacted, not a code section: read it under `/us/session-laws`; not charged) or `error` (we failed to process it; refunded). examples: - null type: object required: - citation - raw - type - subtype - resolved title: ExtractedCitationRow description: >- One distinct citation found in the text, and what the resolver said about it. ExtractCitationsCounts: properties: found: type: integer title: Found description: Distinct citations found (before `maxCitations`). resolved: type: integer title: Resolved description: How many resolved to a section. unresolved: type: integer title: Unresolved description: How many were sent to the resolver and did not. skipped: type: integer title: Skipped description: How many were not resolved (`skipped` on the row). type: object required: - found - resolved - unresolved - skipped title: ExtractCitationsCounts ApiFieldError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Loc description: >- Where the bad value is: `body`, `query` or `path`, then the parameter name exactly as you send it (camelCase), then list indexes. A bare `["body"]` means the body as a whole was not a JSON object. examples: - - body - corpusType msg: type: string title: Msg description: What is wrong with the value, in plain English. examples: - Input should be 'USC', 'CFR' or 'STATE' type: type: string title: Type description: >- Machine-readable error kind, e.g. `missing`, `literal_error`, `json_invalid`. examples: - literal_error type: object required: - loc - msg - type title: ApiFieldError description: One rejected field in a 422 response. MissReasonCandidate: properties: state: type: string title: State description: The jurisdiction to pass as `state` to resolve this one. examples: - co actId: type: string title: Actid description: The section's id. examples: - REG_CO_T8_S1206-2 citation: anyOf: - type: string - type: 'null' title: Citation description: Its own citation, as it appears in results. examples: - 8 CCR 1206-2 subsection: anyOf: - type: string - type: 'null' title: Subsection description: The pinpoint the citation carried, if any. type: object required: - state - actId title: MissReasonCandidate description: A held section an ambiguous citation could mean. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: vq_key_* description: >- API key issued from the developer dashboard. Pass as `Authorization: Bearer vq_key_...` (preferred). ApiKeyHeader: type: apiKey in: header name: X-API-Key description: >- The same API key as a bare header value: `X-API-Key: vq_key_...`. Equivalent to the Bearer form. ApiKeyQuery: type: apiKey in: query name: api_key description: >- The same API key as a query parameter: `?api_key=vq_key_...`. Use only where you cannot set a header. A URL can end up in proxy and server logs, browser history and shared links, so prefer either header form, and rotate a key that has leaked. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.