Corpus API
Semantic search and citation over US federal + state law — built for agents and apps.
Quick start
Claim an approved alpha key at /settings (current account grant: 500 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/searchq*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/browsecodeBodyId*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— carriesupgradeUrl.403 insufficient_scope— key lacks the route's scope.422 validation_error— a required parameter is missing/invalid.429 rate_limited— carriesRetry-AfterandretryAfterSec.
Every success carries X-Credits-Remaining and X-RateLimit-Limit. Free tier is 30 req/min · 1000/day.
Credits & pricing
Credits live in one non-expiring account wallet shared by every key. Approved alpha access grants 500 credits once; creating another key grants zero. One-time packs, no subscription:
| Pack | Price | Credits | Rate limit |
|---|---|---|---|
| Starter | $5 | 1,000 | 60/min |
| Pro | $20 | 5,000 | 120/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 at https://corpuslaw.us/api/mcp — the same corpus, keys, and credits, callable from Claude Code, Claude Desktop, Cursor, or any MCP client. Research tools (search_law, get_law_node, list_coverage) plus a free agent-native formation suite (formation_requirements, lookup_naics, formation_handoff): your agent runs the whole LLC/nonprofit intake in its own conversation, validates the draft for free, and hands the user a fully pre-loaded link to review and pay. Nothing is re-asked.
Claude Code — one command:
claude mcp add --transport http corpus https://corpuslaw.us/api/mcp
Full guide — per-client setup, the complete tool reference, and step-by-step research + formation walkthroughs: /docs/mcp.
Walkthroughs
The common loops, end to end (full copy-paste versions in the repo doc and at the links):
- Citation-safe research:
/coverage(is the jurisdiction searchable?) →/search?q=…&jurisdiction=MS→/node/{nodeId}for full text +provenance→ cite the returnedcitationstring verbatim. - Zoning with real citations:
/gis/CA-SF→ gate oncitationQuality === "linked"→ follow each zone'snodeIdto the defining legal section. - Budget-aware agents:
/mebefore a run, watchX-Credits-Remainingon every success, branch on402/429(both carry recovery fields). - Formation tracking:
/formation/status/{orderId}?token=…— stagesdetails → payment → setup → final_review → filing → completed. - Form a company from an agent: the free MCP intake loop — see /docs/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.