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 /statutes/search. Scope it with corpusType and state for tighter results.

curl -X POST https://api.vaquill.ai/api/v1/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/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/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://..."
    }
  ],
  "total": 5,
  "offset": 0,
  "hasMore": true,
  "query": "civil rights deprivation under color of law",
  "processingTimeMs": 412.6
}

total is the count returned on this page, not the corpus-wide match count. Use hasMore to decide whether to fetch the next page. See Pagination.

Fetch the section and its body

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

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

# Full text
curl https://api.vaquill.ai/api/v1/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/statutes/section/{act_id}",
    headers=headers,
).json()

body = requests.get(
    f"https://api.vaquill.ai/api/v1/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/statutes/section/${actId}`,
    { headers },
  )
).json();

const body = await (
  await fetch(
    `https://api.vaquill.ai/api/v1/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 /statutes/coverage to see the corpus legend and, for each jurisdiction, which corpusType tokens have data. Pass one of those tokens back into /statutes/search.

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

import requests

cov = requests.get(
    "https://api.vaquill.ai/api/v1/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/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.

Rate limits

Per-plan limits and how to back off on a 429.

Best practices

Scope queries, cache coverage, and handle errors well.

Get Started

Core Concepts

Working with the API

Data

Grounding AI

Recipes

Use Cases

Resources

Next steps

Pagination

Rate limits

Best practices

​Next steps

Pagination

Rate limits

Best practices

Next steps