Corpus API
Semantic search and citation over US federal + state law — built for agents and apps.
Which formation providers have a public API? See the comparison.
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.
Formation operations use zero research/API credits. Requirements, NAICS codes, the price grid, provider comparison and public checkout/status need no API key for USDC or hosted-card payment. When prepaid formation packs are enabled, explicit rail: "pack" requires the owner’s formation-scoped API key and redeems 1 prepaid formation credit; any state-fee increase is paid separately through the returned Stripe link. For other rails, a valid key only attributes the order.
Endpoints
| Method & path | What it does | Credits |
|---|---|---|
GET /api/v1/searchq* page limit mode jurisdiction codeBody facets | 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: 20 LLC services + 1 adjacent 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 state fees (filing fee + the state's processing charges), 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. The totals are list prices; while the founding-order cohort has slots left, foundingOffer reports the discount, the cap and the slots remaining, and it is null once the cohort is full. Keyless and uncredited: a published price that costs a credit to read is not published. | 0 |
GET /api/v1/formation/requirementsentityType* state* | The intake checklist for one state and entity type, from the same validator every formation order is checked against: every required field, the state's own questions with the stateSpecificAnswers key each answer goes under, the duties the founder owes after formation, live itemized pricing (expedite, EIN add-on and the founding discount where they apply), and the registered-agent acknowledgements with the consent version an order must send. The structured twin of the formation.requirements MCP tool. Keyless and uncredited. | 0 |
GET /api/v1/formation/naicsq* format | Candidate NAICS codes (typically 2–6) for a plain-English description of what the business does. A code is required for every LLC, and for nonprofits in AK, CT, LA, MS, TN and WV: confirm one with the founder. The same matcher as the formation.lookup_naics MCP tool and /api/naics. Describe the work, not a person: text that looks like personal information is refused. Keyless and uncredited. | 0 |
POST /api/v1/formation/ordersJSON body{
"draft": {
"entityType": "llc",
"state": "WY",
"proposedName": "Acme Robotics LLC",
"contactEmail": "[email protected]",
"naicsCode": "541715",
"businessActivity": "Designs and sells warehouse robots.",
"principalOffice": {
"line1": "1 Main St",
"city": "Cheyenne",
"state": "WY",
"postalCode": "82001"
},
"management": "member_managed",
"parties": [
{
"role": "member",
"fullName": "Ada Lovelace"
},
{
"role": "organizer",
"fullName": "Ada Lovelace"
}
]
},
"contactEmail": "[email protected]",
"consent": {
"version": "4692df2a6585",
"registeredAgentAcknowledgements": true
},
"idempotencyKey": "acme-7f3c9a2e",
"testMode": true
} | Creates the founder's LLC or nonprofit order and a payment request: the order formation.checkout creates over MCP, through the same code and gates. No key needed; a valid bearer key attributes the order. Send the complete draft, the founder's contactEmail, consent { version, registeredAgentAcknowledgements: true } after reading the founder the acknowledgements from GET /api/v1/formation/requirements verbatim, and an idempotencyKey reused on every retry. The response is a payment link (a Stripe checkout link, or a USDC payPageUrl), or on a queue-lane order a submission promise to read the founder and accept with POST /api/v1/formation/orders/{orderId}/checkout. The EIN add-on is not sold here. After payment the founder must click the confirmation link Corpus emails within 48 hours, or the order is refunded. Nothing is filed before that confirmation, and then Corpus reviews the filing before it reaches the state, unless the founder chose to skip review on an expedited order. testMode: true returns a simulated order that is never stored, charged or filed. | 0 |
POST /api/v1/formation/orders/{orderId}/checkoutorderId* JSON body{
"trackingToken": "<trackingToken>",
"acceptPromise": {
"termDays": 30
}
} | The continuation of an order POST /api/v1/formation/orders created: on a queue-lane order, send acceptPromise with the term the founder accepted to get the payment link; on any order, call it again for a fresh link after one expired, or with rail: "usdc" to pay in USDC (a USDC request cannot be switched back to Stripe while it is open). The second formation.checkout call over MCP. A test_ orderId continues a simulated order. | 0 |
GET /api/v1/formation/orders/{orderId}orderId* X-Tracking-Token* | The payment state of an order POST /api/v1/formation/orders created (awaiting, processing, paid, expired, failed, underpaid, held for staff review, including a payment hold or dispute, or refunded in full), its rail, and whether the founder has confirmed by email (pending, confirmed, or expired once the window closes unconfirmed, when the order is listed for a refund). Reading it also records a USDC payment that just arrived. After the founder confirms, orderState follows the order through review and filing. The tracking token travels in a header, never the URL. The formation.payment_status MCP tool. Beside the payment state, it returns the order's progress, the formation.status MCP tool's view: phase, filingSubmitted (the only field that means the state has the filing), dated milestones, the state's confirmationNumber and the certificateUrl when they exist, and a timeline of dated state changes (order_created, paid, founder_confirmed, review_approved, submitted, state_confirmed, certificate_available, …) with the confirmation number and certificate link on their entries. A test_ orderId reports the simulated outcome its create call asked for. | 0 |
POST /api/v1/formation/orders/{orderId}/webhooksorderId* X-Tracking-Token* JSON body{
"url": "https://agent.example.com/corpus/webhooks"
} | Registers an https endpoint that receives a signed POST at each change of the order's state, so an agent need not poll. The formation.webhook MCP tool. At most 3 active endpoints per order. The secret is shown once; a formation.webhook.test delivery follows at once. { remove: true, subscriptionId } stops deliveries to one. A test_ orderId sends one signed formation.webhook.test during the request and stores nothing. Deliveries are signed to the Standard Webhooks spec (standardwebhooks.com): webhook-id, webhook-timestamp and webhook-signature headers, where webhook-signature = v1,base64(HMAC-SHA256(base64-decoded secret after whsec_, `${webhook-id}.${webhook-timestamp}.${raw body}`)). Reject timestamps older than 5 minutes and dedupe on webhook-id. The body is { type, timestamp, data }, where data is the order's lifecycle (phase, filingSubmitted, dated milestones, confirmationNumber, certificateUrl): no founder personal data. Events: formation.webhook.test, formation.order.paid, founder_confirmed, confirmation_expired, in_review, review_approved, submitted, accepted, certificate_available, completed, failed and cancelled. A failed delivery is retried for about 45 hours; a 410 Gone removes the endpoint. | 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. Counts refresh daily; a jurisdiction delivered since then appears in uncountedJurisdictions, searchable but without counts. A coverageNote names a code that Corpus carries only in part.
