Section Identifiers

Every section in the Vaquill AI corpus has one canonical identifier: its actId. It is stable, unique, and the key you use to fetch a section’s metadata and full text. You never construct an actId by hand. You get it from search results and pass it back to the section endpoints.

What an actId looks like

actId values encode the section’s place in the source hierarchy. A few examples:

actId	Points to
`USC_T42_C21_S1983`	42 U.S.C. Chapter 21, Section 1983
`CFR_T17_P240_S240_10b5_1`	17 CFR Part 240, Section 240.10b5-1
`USC_T15_C1_S1`	15 U.S.C. Chapter 1, Section 1

State sections follow the same idea, encoding the state’s code and section structure. Treat the whole string as an opaque key: read it from a result, store it, and pass it back unchanged.

The workflow

Search to get an actId

POST /us/statutes/search returns result objects, each with an actId.

Fetch section metadata

GET /us/statutes/section/{actId} returns the full result object for that one section (citation, hierarchy, source URLs).

Fetch full text

GET /us/statutes/section/{actId}/body returns the section’s full text. Returned only when text is available.

Optional: fetch its neighbors

GET /us/statutes/section/{actId}/related returns the section’s immediate statutory neighbors - the previous and next section within the same container (chapter, part, or code). This is not numeric adjacency; it’s what a lawyer would actually turn to next when reading a section in context.

Result and hierarchy fields

Search results and the section object share the same shape. Alongside actId, these fields describe where a section sits and how to cite it:

Field	Meaning
`titleNumber`	The title or code number (may be alphanumeric, e.g. `13A`)
`titleName`	The title’s name
`chapter`	The chapter number
`chapterName`	The chapter’s name
`sectionNumber`	The section number within the chapter
`displayPath`	A human-readable path through the hierarchy
`breadcrumb`	An array of hierarchy levels, from broadest to the section
`citation`	The full legal citation
`citationShort`	A compact citation form

titleNumber can be alphanumeric (some states use ids like 13A), so treat it as a string, not an integer.

Example: search, then fetch

This walks the full path: run a search, take the first actId, fetch its metadata, then fetch its body.

# 1. Search
curl -X POST https://api.vaquill.ai/api/v1/us/statutes/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "civil action for deprivation of rights", "corpusType": "USC", "limit": 1}'

# 2. Fetch metadata for the returned actId
curl https://api.vaquill.ai/api/v1/us/statutes/section/USC_T42_C21_S1983 \
  -H "Authorization: Bearer vq_key_..."

# 3. Fetch full text
curl https://api.vaquill.ai/api/v1/us/statutes/section/USC_T42_C21_S1983/body \
  -H "Authorization: Bearer vq_key_..."

import requests

headers = {"Authorization": "Bearer vq_key_..."}

# 1. Search
search = requests.post(
    "https://api.vaquill.ai/api/v1/us/statutes/search",
    headers=headers,
    json={
        "query": "civil action for deprivation of rights",
        "corpusType": "USC",
        "limit": 1,
    },
).json()
act_id = search["results"][0]["actId"]

# 2. Fetch metadata
section = requests.get(
    f"https://api.vaquill.ai/api/v1/us/statutes/section/{act_id}",
    headers=headers,
).json()["section"]
print(section["citation"], "-", section["displayPath"])

# 3. Fetch full text
body = requests.get(
    f"https://api.vaquill.ai/api/v1/us/statutes/section/{act_id}/body",
    headers=headers,
).json()
print(body["plain"][:500] if body["available"] else "text unavailable")

const headers = { Authorization: "Bearer vq_key_..." };

// 1. Search
const search = await (
  await fetch("https://api.vaquill.ai/api/v1/us/statutes/search", {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      query: "civil action for deprivation of rights",
      corpusType: "USC",
      limit: 1,
    }),
  })
).json();
const actId = search.results[0].actId;

// 2. Fetch metadata
const section = (
  await (
    await fetch(
      `https://api.vaquill.ai/api/v1/us/statutes/section/${actId}`,
      { headers },
    )
  ).json()
).section;
console.log(section.citation, "-", section.displayPath);

// 3. Fetch full text
const body = await (
  await fetch(
    `https://api.vaquill.ai/api/v1/us/statutes/section/${actId}/body`,
    { headers },
  )
).json();
console.log(body.available ? body.plain.slice(0, 500) : "text unavailable");

A 404 on either section endpoint means no section was found, and the /body endpoint returns text only when it is available. Check available before reading html or plain.

When an actId misses

The batch route POST /us/statutes/sections takes up to 50 actIds and tells you WHY each one missed, which is the difference between a bug in your code and a gap in ours. Alongside sections it returns notFound (the bare ids) and notFoundDetail, one entry per missed id:

Field	Contains
`actId`	The identifier from your request that did not resolve.
`reason`	`assembled_id` or `not_in_corpus`. See below.
`didYouMean`	Real act ids carrying the section number your id pointed at, best first, at most 3.

reason: "assembled_id" means this id does not exist, but the section does, under the ids in didYouMean. That is almost always an id built from a citation. The chapter, article and part segments are not derivable from a citation, so Tex. Property Code § 93.005 is STATE_TX_Cpr_C93_S93.005, not STATE_TX_C93_S93.005. Send one of the suggested ids back and you get the section. reason: "not_in_corpus" means nothing matching was found: either the id is malformed beyond recovery, or the section is genuinely absent. Check GET /us/statutes/coverage for that jurisdiction before reading it as missing coverage.

Ids in notFound are not charged, so a batch with misses costs less than 50 times the per-section rate. notFoundDetail is diagnostic only and never charged. It can come back empty if the suggestion lookup is unavailable, so treat it as a hint rather than a contract.

If you are starting from a citation rather than a search result, use GET /us/statutes/resolve instead of assembling an id. That is what it is for.

Finding a section’s neighbors

GET /us/statutes/section/{actId}/related returns the sections immediately before and after the one you already have, within the same container:

cURL

curl https://api.vaquill.ai/api/v1/us/statutes/section/USC_T42_C21_S1983/related \
  -H "Authorization: Bearer vq_key_..."

The response carries previous and next arrays (each a full section object, same shape as a search result) plus a container label naming what they’re neighbors within (e.g. the enclosing chapter or part). Useful for “show me the surrounding sections” without a second search call - reading § 1983 alongside §§ 1981-1982 and 1985 in one request, for example.

Response Formats

The text formats and source URLs a section can carry.

Corpus Types

The corpusType tokens you filter a search by.

DATA COVERAGE

USE CASES

GET STARTED

CORE CONCEPTS

LAW CHANGE ALERTS

WORKING WITH THE API

GROUNDING AI

RECIPES

What an actId looks like

The workflow

Result and hierarchy fields

Example: search, then fetch

When an actId misses

Finding a section’s neighbors

Response Formats

Corpus Types

​What an actId looks like

​The workflow

​Result and hierarchy fields

​Example: search, then fetch

​When an actId misses

​Finding a section’s neighbors

​Related

Response Formats

Corpus Types

What an actId looks like

The workflow

Result and hierarchy fields

Example: search, then fetch

When an actId misses

Finding a section’s neighbors

Related