Corpus API

Semantic search and citation over US federal + state law — built for agents and apps.

Discovery JSON OpenAPI 3.1 spec Get an API key →

Quick start

Create a key at /settings (free tier: 100 credits, 10 requests/min), then:

curl -H "Authorization: Bearer $CORPUS_API_KEY" \
  "https://corpuslaw.us/api/v1/search?q=distillery%20permit&limit=3"

Authentication

Pass your key in the Authorization header on every request:

Authorization: Bearer cp_your_key_here

Header only. Query-parameter auth (?api_key=) is disabled in production because it leaks keys into access logs, Referer headers, and browser history.

Endpoints

Method & path	What it does	Credits
`GET /api/v1/search` `q`*`pagelimitmodejurisdictioncodeBodyfacets`	Hybrid semantic + keyword search over every ingested provision. Returns ranked results with citations, headings, and snippets. Check /api/v1/coverage first to see which jurisdictions are searchable.	1
`GET /api/v1/node/{id}` `id`*	Full text, citation, and ancestor hierarchy for a single codex node. Get the id from a search result's `nodeId`.	1
`GET /api/v1/code-bodies`	Every code body (e.g. 'Mississippi Code', 'US Code'). Use a returned id with /api/v1/browse to walk its hierarchy.	1
`GET /api/v1/browse` `codeBodyId`*`parent`	List the immediate children of a code body (or of a parent node within it) — titles, chapters, sections.	1
`GET /api/v1/gis/{shortCode}` `shortCode`*	Published zoning polygons for a municipal jurisdiction, with per-zone citations. Check `citationQuality`: 'linked' means every zone cites a real codex node; 'pending' means some citations are placeholders.	5
`GET /api/v1/coverage`	Per-jurisdiction inventory: node counts, searchable-chunk counts, GIS status, citation quality, and a `placeholder` flag for jurisdictions that are listed but not yet searchable. Call this before searching so an empty result isn't mistaken for a broken API.	1
`GET /api/v1/me`	Live credit balance, tier, rate limits, recent ledger entries, and upgrade options with prices. The budget-introspection endpoint for agents.	1
`GET /api/v1/formation/status/{orderId}` `orderId``token`	Status of an LLC/nonprofit formation order. Requires the per-order tracking token issued when the order was created.	1

* required parameter

Errors & rate limits

Errors share one shape so agents can branch on the code:

{ "error": "insufficient_credits", "message": "…", "upgradeUrl": "…" }

401 invalid_api_key — missing/invalid key.
402 insufficient_credits — carries upgradeUrl.
403 insufficient_scope — key lacks the route's scope.
422 validation_error — a required parameter is missing/invalid.
429 rate_limited — carries Retry-After and retryAfterSec.

Every success carries X-Credits-Remaining and X-RateLimit-Limit. Free tier is 10 req/min · 100/day.

Credits & pricing

One-time credit packs, no subscription, credits don't expire:

Pack	Price	Credits	Rate limit
Starter	$5	1,000	30/min
Pro	$20	5,000	60/min
Bulk	$50	15,000	300/min

Most calls cost 1 credit; GIS layer calls cost 5. Buy at /settings.

MCP server (in-agent)

Corpus is also a Model Context Protocol server. Point Claude Desktop, Cursor, or any MCP client at https://corpuslaw.us/api/mcp to search and cite law from inside an agent. Tools: search_law, get_law_node, list_coverage, account_status (free credit-balance check). Anonymous access is rate-limited; supply a Bearer key for metered higher limits.

{
  "mcpServers": {
    "corpus-legal": {
      "type": "http",
      "url": "https://corpuslaw.us/api/mcp"
    }
  }
}

Coverage before you search

Call /api/v1/coverage (or the list_coverage MCP tool) to see which jurisdictions are ingested and searchable. Jurisdictions flagged placeholder: true are listed but not yet searchable — an empty search there is expected, not a bug.