Corpus API
Semantic search and citation over US federal + state law — built for agents and apps.
Quick start
Create a key at /settings — self-serve and instant, no review step (1,000 free searches a month at 30 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 |
GET /api/v1/compare/llc-services | The full dated dataset behind the formation.compare MCP tool: 19 providers with prices, registered-agent renewal terms, machine-interface capabilities, and Agentic Readiness scores, each verified against primary sources. Corpus is one of the compared providers and is scored with the same rubric, gaps included. Keyless and uncredited so the claims stay independently checkable. | 0 |
GET /api/v1/formation/prices | What Corpus charges to form an LLC or nonprofit corporation in every state it files in, itemized into the pass-through state filing fee, first-year registered agent, and Corpus service fee. Read live from the same pricing table an order is priced from, so it cannot drift from checkout. Keyless and uncredited: a published price that costs a credit to read is not published. | 0 |
* 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
Research is metered in two stages. First a free monthly allotment — 1,000 searches a month on a free key, renewing on the 1st, and 5,000 a month permanently once you form a company through Corpus. Only past it do calls reach the credit wallet: one non-expiring balance shared by every key, topped up with the packs below. This REST API and the MCP server meter identically, against one shared allotment — the same key means the same thing on either. Every response carries X-Research-Allotment-Remaining alongside X-Credits-Remaining. Packs are one-time, 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 (law.search, law.get_node, law.list_coverage) plus a free agent-native formation suite (formation.requirements, formation.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. The founder chooses card or, when offered, USDC on Solana at checkout. The agent hands off the link; it does not handle payment credentials. 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 law.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.