> ## 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.

# Best Practices

> Get better results and build resilient integrations

A few habits make Vaquill AI integrations faster, cheaper, and more accurate. Follow these when you move from a prototype to production.

## Scope every query

Pass `corpusType` (and `state` for state-scoped corpora) on `POST /us/statutes/search`. Scoping does two things: it sharpens relevance by removing off-target jurisdictions, and it makes your [pages](/docs/api-guide/pagination) more predictable. An unscoped search ranks across the whole corpus, so a `state`-specific answer can be crowded out by federal or other-state matches.

```json theme={"theme":"github-dark"}
{ "query": "security deposit return deadline", "corpusType": "STATE", "state": "ca" }
```

You can scope tighter still. `code` (state, e.g. `tx_pe`) and `titleNumber` (USC/CFR) narrow a search to one code or title. Get a state's `code` values from `GET /us/statutes/divisions?corpusType=STATE&state=XX`. To go one level deeper, `chapter` (USC/state) and `part` (CFR) confine a search to a single subtree. These are the search-side of the `parent` object on every result: take a hit's `parent` and pass it straight back to search that section's neighbors. `chapter`/`part` must be paired with `titleNumber` or `code` (which `parent` always carries), since a chapter number alone repeats across every title.

```json theme={"theme":"github-dark"}
{ "query": "damages for intentional discrimination", "corpusType": "USC", "titleNumber": 42, "chapter": "21" }
```

## Choose the right matchType

`matchType` is the only exact-match control in the API, and it is what you reach for when hybrid ranking is too loose.

| Value | Behaviour | Use it for |
| - | - | - |
| `any` (default) | Hybrid semantic plus keyword ranking | Natural-language questions |
| `all` | Every query term must appear in the text | Multi-term lookups where recall is hurting you |
| `phrase` | The exact phrase must appear | Defined terms and statutory phrases |

`any` ranks on intent, so a query can rank a section that shares no wording with it.
That is what you want for "how long does a landlord have to return a deposit", and wrong for "material adverse effect", where a section that merely discusses the idea is noise.

`all` and `phrase` trade recall for precision.
Both can return nothing. An empty result under them means no section *we ranked for your query* carried those terms, which is not the same as the corpus holding none, so fall back to `any` and scope the query more tightly rather than concluding there is a coverage gap.

```json theme={"theme":"github-dark"}
{ "query": "material adverse effect", "corpusType": "STATE", "state": "de", "matchType": "phrase" }
```

<Tip>
  To pull up one specific section, pass its citation as the query (for example `42 U.S.C. § 1983`) and leave `matchType` at `any`. It resolves to that section at rank 1. `GET /us/statutes/resolve` does the same job for less when you already hold a well-formed citation.
</Tip>

## Control what a search returns

* `excerptChars`: how much matching text each result carries (default 500, up to 4000). The excerpt is windowed around the match and can begin mid-section, dropping a leading subsection marker, so it is a ranking preview and not safe to quote.
* `includeBody`: attaches each hit's full text on `body` in the same call. It bills each row that returns text on top of the search, so it multiplies with `limit`. Use it with a small `limit`, and read `creditsConsumed`.

For text you intend to quote, use `body` or `GET /us/statutes/section/{actId}/body`, never a raised `excerptChars`.

Each result also carries a `parent` object: the `/us/statutes/divisions` query that lists the section's siblings, so you can walk up the hierarchy from any hit. Section responses also include amendment provenance (`sourceCredit`, `amendmentYears`, `lastAmendedYear`, `publicLaws`, `federalRegisterCitations`).

## Discover before you search

Two endpoints answer everything about what is queryable.

* `GET /us/statutes/coverage` is the corpus matrix. Read a jurisdiction's `corpora` keys and pass one back as `corpusType`. This avoids guessing a token that has no data for that state and wasting a call on an empty result.
* `GET /us/statutes/divisions` is the hierarchy. Pass `corpusType=STATE&state=XX` to list a state's individual statutory codes (Penal, Civil, and so on) and their `code` values, or drill in with `titleNumber`, `code`, `chapter` and `part`.

## Cache coverage

Coverage grows weekly, not hourly. Cache `/us/statutes/coverage` and `/us/statutes/divisions` for hours or a day rather than calling them on every request. They still count against your rate limits.

## Store the actId values you care about

The `actId` (for example `USC_T42_C21_S1983`) is the handle for a section. Once a search surfaces a section your product depends on, store its `actId` and go straight to `GET /us/statutes/section/{actId}` or `.../body` on later runs. That skips the search entirely.

Store the citation next to it. An `actId` survives an amendment and a repeal, but it changes if the section is renumbered, so a lookup that stops resolving is a cue to re-resolve by citation through `GET /us/statutes/resolve` rather than to drop the record. See [Section identifiers](/docs/api-guide/concepts/section-ids).

## Retry on 429, handle 402

* On `429`, respect the `Retry-After` header and use exponential backoff. See [Errors](/docs/api-guide/errors).
* On `402`, stop, surface a clear message, resolve it in your account dashboard, then retry.
* Both are expected in production. Build for them rather than treating them as fatal.

## Treat relevanceScore as a within-response rank

`relevanceScore` (0 to 1) orders results **within a single response**. It is a relative rank, not a calibrated confidence score.

Do not compare scores across different queries and do not use a fixed threshold (for example "drop anything below 0.7") to decide what to keep. To narrow results, tighten `query`, `corpusType`, and `state` instead.

To tell whether the corpus has anything on point at all, read `noGoodMatch` on the search response instead of thresholding scores yourself:

* `true`: nothing in the corpus looks on point for this query (or no rows came back). Say so, rather than presenting the rows as an answer.
* `false`: something on point was found, or the top row is an exact citation match.
* `null`: the ranking was degraded (`rankingDegraded: true`), so its scores cannot be judged. Retry the query.

To judge how likely the top result is to be the right section, read `matchQuality`:

| Value | Meaning |
| - | - |
| `exact` | The top result is a citation or section-number match. |
| `strong` | In our measurements the top result was correct about 94% of the time (about 91% when the answer is a statute or regulation). |
| `moderate` | Correct about 67% of the time. Show the top few results, not just the first. |
| `weak` | Correct about 35% of the time. Treat the results as leads to verify. |
| `none` | Same as `noGoodMatch: true`. |
| `null` | The ranking was degraded; retry. |

The tiers are measured on our labelled evaluation set and may be re-cut as the index changes. Treat a value you do not recognise as `moderate`.

`noGoodMatch` and `matchQuality` are properties of the query, so every page of one search carries the same values.
It says nothing about whether the top result is the right section. A same-topic section from the wrong jurisdiction or the wrong layer (a state statute for a federal question, a regulation for a statute) can rank first, so check `citation` and `state` before you rely on it.

Browse is ordered differently. `GET /us/statutes/divisions` returns divisions in statutory (natural) order, the way a person reads a code, not by relevance: `9` sorts before `10`, and `240.9` before `240.10`. Reach for search when you want the most on-point section, and for browse when you want the structure in order.

## Link users to official sources

Each result carries source links (`htmlUrl`, `pdfUrl`, `xmlUrl`, `textUrl`, `docxUrl`, `stateHtmlUrl`, `govInfoHtmlUrl`, `govInfoPdfUrl`, `externalUrl`; any may be null). For user-facing deep links, prefer the official government link (state legislature or govinfo.gov) so readers land on authoritative text. This keeps your product grounded and verifiable.

## Related

<CardGroup cols={2}>
  <Card title="Pagination" href="/docs/api-guide/pagination">
    Page predictably with `limit`, `offset`, and `hasMore`.
  </Card>

  <Card title="Coverage" href="/docs/api-guide/coverage">
    See the full jurisdiction and corpus matrix.
  </Card>
</CardGroup>


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