Query Regulations

POST /api/v1/regulations/query

Returns the regulatory chunks most relevant to a natural-language query. Use it to ground answers, citations, or analyses in the specific passages that address the question — pair it with your own model to build retrieval-augmented generation.

Each result groups one or more excerpts under their parent regulation, with the section path identifying where in the document each excerpt lives.

Request Body

{
  "query": "provisional credit timing requirements",
  "limit": 10,
  "filters": {
    "authorities": ["cfpb"],
    "jurisdictions": ["us-federal"]
  }
}

Fields

Name	Type	Required	Description
query	string	yes	Natural-language query matched against the corpus. Min 1, max 2000 characters.
limit	integer	no	Maximum number of chunks to return. Min 1, max 50, default 10.
filters	object	no	Restrict the search to a subset of the corpus. See Filters.

Filters

All filter fields are optional, repeatable arrays. Values are OR’d within a field and AND’d across fields.

Name	Type	Description
ids	string[]	Restrict to specific regulations. Up to 100 ids.
authorities	string[]	Filter by authority id (e.g., cfpb, occ, fincen). Up to 50.
jurisdictions	string[]	Filter by jurisdiction id (e.g., us-federal, us-state:ny). Up to 50.

Response

{
  "results": [
    {
      "regulation": {
        "id": "cmdoc_01HXZ3K4M7QR9VP2N8WYJF5GTB",
        "category": "regulation",
        "title": "Electronic Fund Transfers",
        "authorities": ["cfpb"],
        "jurisdictions": ["us-federal"],
        "description": "Regulation E error-resolution requirements for financial institutions, including investigation timelines and provisional credit obligations.",
        "updatedAt": "2026-04-09T00:00:00Z",
        "sourceUrl": "https://www.ecfr.gov/current/title-12/chapter-X/part-1005"
      },
      "chunks": [
        {
          "text": "If the financial institution is unable to complete its investigation within 10 business days, the institution shall provisionally credit the consumer's account...",
          "startOffset": 12450,
          "endOffset": 13120,
          "sectionPath": "Electronic Fund Transfers > § 1005.11 > (c)(2)"
        }
      ]
    }
  ]
}

Each result is a Regulation Citation Object — the same shape returned by the Create Screen Analysis Job — a parent regulation paired with one or more excerpts from it.

Hits are grouped by parent regulation: if multiple chunks in the search result come from the same regulation, they are merged into a single citation with the chunks listed in rank order. Citations themselves are returned in the rank order of each regulation’s best-scoring chunk (top result first).

Result Fields

Field	Type	Description
regulation	Regulation Summary Object	The parent regulation for the chunks below.
chunks	CitationChunk[]	One or more excerpts from the regulation that matched the query, in rank order. See Regulation Citation Object.

Chunk

Field	Type	Description
text	string	Verbatim regulation text for this chunk. Not generated content.
startOffset	integer or null	Byte offset where the excerpt begins in the regulation’s UTF-8 source text. null when unavailable (legacy ingestion). To slice the original source, fetch via the Get Regulation Content and slice as bytes (e.g., Buffer.from(text, 'utf-8')). For ASCII-only content these match character offsets.
endOffset	integer or null	Byte offset where the excerpt ends. Same conventions as startOffset.
sectionPath	string or null	>-delimited breadcrumb showing where the chunk lives within its document (e.g., Electronic Fund Transfers > § 1005.11 > (c)(2)). For documents without extractable section structure (typically single-section rules or unstructured statutes), falls back to the document title alone. null when nothing could be derived.

The chunk shape is identical across this endpoint, Screen Analysis citations, and the Get Regulation Content — all use byte offsets in the UTF-8 source. A query chunk’s startOffset/endOffset can be passed straight to the Read Content API to fetch a wider context window around the excerpt.

For a formal regulatory citation (e.g., 12 CFR 1005.11(c)(2), 15 USC § 1681i(a)), use the parent regulation.id to fetch full structured attributes via the Get Regulation Details — citation conventions vary by document category and are constructed per-category from those attributes (see the Regulation Detail Object page).

Composing With an LLM

This endpoint returns chunks, not answers. The standard pattern is:

1. Call POST /api/v1/regulations/query with the user’s question.
2. For each citation in results, concatenate regulation.title plus the citation’s chunks[].text into your prompt context.
3. Ask your model to answer using only the provided chunks, and attribute each claim with regulation.title + sectionPath (or a formal citation derived from the Regulation Detail Object attributes).

Each chunk carries sectionPath for in-document attribution, and each citation carries the full regulation object (including id and sourceUrl) for source-level attribution.

Non-goals

The endpoint does not generate text, summarize, or answer the query — it returns the underlying chunks for you to compose with. It does not return paginated results — the response contains up to limit chunks total (grouped into citations), or fewer if the corpus is smaller after filtering.

Rate Limits

Calls are rate-limited per API key. Each call is billed at the same credit rate as other regulation operations (browse, read). On limit exceeded, the endpoint responds with 429 rate_limit_exceeded and a Retry-After header; see Errors for the shared error envelope.