Quickstart

This guide takes you from zero to your first grounded statute answer. You will search the corpus, take an actId from the results, fetch that section’s metadata and full text, and discover what is queryable. Every path is prefixed with /api/v1 and every request needs an Authorization: Bearer vq_key_... header.

Get an API key

Create a key in your dashboard under API Keys. Copy it once, it will not be 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. The top-level fields describe the page, and each results entry carries a citation, an excerpt, and links to the official source.

{
  "results": [
    {
      "actId": "USC_T42_C21_S1983",
      "citation": "42 U.S.C. § 1983",
      "citationShort": "42 USC 1983",
      "title": "Civil action for deprivation of rights",
      "corpusType": "USC",
      "state": null,
      "year": 1996,
      "relevanceScore": 0.91,
      "excerpt": "Every person who, under color of any statute, ordinance, regulation, custom, or usage...",
      "titleNumber": 42,
      "titleName": "The Public Health and Welfare",
      "sectionNumber": "1983",
      "breadcrumb": ["Title 42", "Chapter 21", "Section 1983"],
      "htmlUrl": "https://...",
      "govInfoPdfUrl": "https://..."
    }
  ],
  "count": 5,
  "offset": 0,
  "hasMore": true,
  "query": "civil rights deprivation under color of law",
  "processingTimeMs": 412.6,
  "creditsConsumed": 4
}

count is how many results came back on this page, not a corpus-wide match count. 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 reads as a corpus-wide total, which it never was. Read count in new code.

creditsConsumed is what this call actually cost. Read it rather than assuming a list price: failed and refunded work bills 0, and includeBody: true bills each row that returns text on top of the search. 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

The corpus 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.

DATA COVERAGE

USE CASES

GET STARTED

BULK, SQL & RIGHTS

CORE CONCEPTS

LAW CHANGE ALERTS

WORKING WITH THE API

GROUNDING AI

RECIPES

Next steps

Pagination

Best practices

​Next steps

Pagination

Best practices

Next steps