Quickstart

This guide walks through a first search, then fetches one section’s metadata and full text using the actId from the results, and finally checks what is queryable. Every path is prefixed with /api/v1 and every request needs an Authorization: Bearer vq_key_... header.

Prefer a GUI? The public Postman collection has every endpoint as a ready-to-run request. Fork it, set your API key as the bearer token, and send.

Get an API key

Create a key in your dashboard under API Keys. Copy it right away, because it is not shown again. See Authentication for details.

Make your first search

Send a natural language query to POST /us/statutes/search. Scope it with corpusType and state for tighter results.

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 rights deprivation under color of law", "corpusType": "USC", "limit": 5}'

import requests

resp = requests.post(
    "https://api.vaquill.ai/api/v1/us/statutes/search",
    headers={
        "Authorization": "Bearer vq_key_...",
        "Content-Type": "application/json",
    },
    json={
        "query": "civil rights deprivation under color of law",
        "corpusType": "USC",
        "limit": 5,
    },
)
data = resp.json()
first = data["results"][0]
print(first["citation"], first["actId"])

const resp = await fetch("https://api.vaquill.ai/api/v1/us/statutes/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer vq_key_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "civil rights deprivation under color of law",
    corpusType: "USC",
    limit: 5,
  }),
});
const data = await resp.json();
const first = data.results[0];
console.log(first.citation, first.actId);

A trimmed response looks like this (captured 2026-10-22; fields that were null are left out of this sample, the live response lists them as null, and only the first of five results is shown). The top-level fields describe the page. Each results entry has a citation, an excerpt, and links to the official source.

{
  "results": [
    {
      "actId": "USC_T42_C21_S1983",
      "citation": "42 U.S.C. § 1983 (2026)",
      "citationShort": "42 U.S.C. § 1983",
      "title": "Civil action for deprivation of rights",
      "corpusType": "USC",
      "state": "federal",
      "year": 2026,
      "relevanceScore": 0.863,
      "excerpt": "Every person who, under color of any statute, ordinance, regulation, custom, or usage, of any State or Territory or the District of Columbia, subjects, or causes to be subjected, any citizen of the United States or other person within the jurisdiction thereof to the deprivation of any rights...",
      "titleNumber": "42",
      "titleName": "THE PUBLIC HEALTH AND WELFARE",
      "sectionNumber": "1983",
      "breadcrumb": [
        { "type": "title", "num": "42", "label": "Title 42", "name": "THE PUBLIC HEALTH AND WELFARE" },
        { "type": "chapter", "num": "21", "label": "Chapter 21", "name": "CIVIL RIGHTS" },
        { "type": "subchapter", "num": "I", "label": "Subchapter I", "name": "GENERALLY" },
        { "type": "section", "num": "1983", "label": "Section 1983", "name": "Civil action for deprivation of rights" }
      ],
      "actStatus": "in_force",
      "currentThrough": "2026-09-18",
      "textUrl": "https://statutes-us.vaquill.ai/usc/olrc/119-111/sections/USC_T42_C21_S1983.txt",
      "externalUrl": "https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title42-section1983&num=0&edition=prelim",
      "sourceUrl": "https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title42-section1983&num=0&edition=prelim"
    }
  ],
  "count": 5,
  "total": 5,
  "offset": 0,
  "hasMore": true,
  "query": "civil rights deprivation under color of law",
  "processingTimeMs": 2339.7,
  "creditsConsumed": 4
}

count is the number of results on this page. It is not a corpus-wide match count, and no such total exists, because the API ranks a bounded candidate set rather than scoring the whole corpus. Use hasMore to decide whether to fetch the next page. See Pagination.The response also carries total, a deprecated alias for count kept for backward compatibility. Its name suggests a corpus-wide total, but it never was one. Read count in new code.

creditsConsumed is what this call actually cost. Failed and refunded work bills 0, and includeBody: true bills each row that returns text on top of the search, so read the field instead of assuming a list price. GET /api-credits/pricing returns the live matrix.

Fetch the section and its body

Take an actId from the results (for example USC_T42_C21_S1983). Call GET /us/statutes/section/{actId} for metadata, and GET /us/statutes/section/{actId}/body for the full text.

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

# 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_..."}
act_id = "USC_T42_C21_S1983"

meta = requests.get(
    f"https://api.vaquill.ai/api/v1/us/statutes/section/{act_id}",
    headers=headers,
).json()

body = requests.get(
    f"https://api.vaquill.ai/api/v1/us/statutes/section/{act_id}/body",
    headers=headers,
).json()

if body["available"]:
    print(body["plain"])

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

const meta = await (
  await fetch(
    `https://api.vaquill.ai/api/v1/us/statutes/section/${actId}`,
    { headers },
  )
).json();

const body = await (
  await fetch(
    `https://api.vaquill.ai/api/v1/us/statutes/section/${actId}/body`,
    { headers },
  )
).json();

if (body.available) console.log(body.plain);

The body endpoint returns html and plain text plus an available flag and a source.

Discover coverage

Coverage grows weekly. Call GET /us/statutes/coverage to see the corpus legend and, for each jurisdiction, which corpusType tokens have data. Pass one of those tokens back into /us/statutes/search.

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

import requests

cov = requests.get(
    "https://api.vaquill.ai/api/v1/us/statutes/coverage",
    headers={"Authorization": "Bearer vq_key_..."},
).json()["data"]

for j in cov["jurisdictions"]:
    if j["hasData"]:
        print(j["code"], list(j["corpora"].keys()))

const cov = (
  await (
    await fetch("https://api.vaquill.ai/api/v1/us/statutes/coverage", {
      headers: { Authorization: "Bearer vq_key_..." },
    })
  ).json()
).data;

for (const j of cov.jurisdictions) {
  if (j.hasData) console.log(j.code, Object.keys(j.corpora));
}

Next steps

Pagination

Page through search results with limit, offset, and hasMore.

Best practices

Scope queries, cache coverage, and handle errors well.

Postman collection

Try every endpoint without writing code.

SDKs

Prefer a client library? The official Python and TypeScript SDKs wrap these calls with retries, typed errors and a spend guard.

DATA COVERAGE

USE CASES

GET STARTED

SDKS

BULK, SQL & RIGHTS

CORE CONCEPTS

LAW CHANGE ALERTS

WORKING WITH THE API

ERROR CODES

GROUNDING AI

RECIPES

Next steps

Pagination

Best practices

Postman collection

SDKs

​Next steps

Pagination

Best practices

Postman collection

SDKs

Next steps