{"openapi":"3.1.0","info":{"title":"Corpus Public API","version":"1.0.0","summary":"Semantic search and citation over US federal + state law, for agents and apps.","description":"Corpus packages US federal and state law as a uniform, agent-consumable API: hybrid semantic + keyword search, full provision text with citations, code-body browsing, municipal zoning layers, and honest coverage metadata. Authenticate with a Bearer API key (create one at https://corpuslaw.us/settings). Every call reports `X-Credits-Remaining`; a 402 carries an `upgradeUrl`. Human docs: https://corpuslaw.us/docs/api.","contact":{"name":"Corpus","url":"https://corpuslaw.us"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://corpuslaw.us","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Search","description":"Find provisions by topic or keyword."},{"name":"Browse","description":"Walk code bodies and read individual provisions."},{"name":"GIS","description":"Municipal zoning layers with citations."},{"name":"Coverage","description":"What jurisdictions are ingested and searchable."},{"name":"Account","description":"Credit balance, usage, and upgrades."},{"name":"Formation","description":"Track entity-formation orders."}],"paths":{"/api/v1/search":{"get":{"operationId":"searchLaw","summary":"Search US federal + state law","description":"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. (Costs 1 credit.)","tags":["Search"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"results":"SearchResultItem[] — nodeId, citation, heading, jurisdiction, codeBody, snippet, score","page":1,"pageSize":20,"total":42,"tookMs":87,"mode":"hybrid"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query (natural language or keywords).","schema":{"type":"string","example":"distillery permit requirements"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Results per page (max 100).","schema":{"type":"integer","default":20}},{"name":"mode","in":"query","required":false,"description":"Retrieval mode. 'hybrid' fuses vector similarity with keyword search.","schema":{"type":"string","enum":["hybrid","semantic","keyword"],"default":"hybrid"}},{"name":"jurisdiction","in":"query","required":false,"description":"Scope to a jurisdiction short code (e.g. TX, US, CA-SF) and its sub-jurisdictions. See /api/v1/coverage for codes.","schema":{"type":"string","example":"TX"}},{"name":"codeBody","in":"query","required":false,"description":"Scope to a single code body by UUID (from /api/v1/code-bodies).","schema":{"type":"string"}},{"name":"facets","in":"query","required":false,"description":"Include facet counts (jurisdiction/tag histograms). Off by default to save latency; most agents don't need them.","schema":{"type":"boolean","default":false}}],"security":[{"bearerAuth":["search"]}]}},"/api/v1/node/{id}":{"get":{"operationId":"getNode","summary":"Fetch one provision by id","description":"Full text, citation, and ancestor hierarchy for a single codex node. Get the id from a search result's `nodeId`. (Costs 1 credit.)","tags":["Browse"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"id":"uuid","citation":"Miss. Code § 67-1-5","heading":"Definitions","text":"…","breadcrumb":["Title 67","…"]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"UUID of the codex node.","schema":{"type":"string","example":"089a2104-d704-4e93-8072-5bbbabc7ace6"}}],"security":[{"bearerAuth":["node"]}]}},"/api/v1/code-bodies":{"get":{"operationId":"listCodeBodies","summary":"List code bodies","description":"Every code body (e.g. 'Mississippi Code', 'US Code'). Use a returned id with /api/v1/browse to walk its hierarchy. (Costs 1 credit.)","tags":["Browse"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"codeBodies":[{"id":"uuid","name":"Mississippi Code","jurisdiction":"MS"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"bearerAuth":["browse"]}]}},"/api/v1/browse":{"get":{"operationId":"browse","summary":"Walk a code body's hierarchy","description":"List the immediate children of a code body (or of a parent node within it) — titles, chapters, sections. (Costs 1 credit.)","tags":["Browse"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"nodes":[{"id":"uuid","heading":"Chapter 1","citation":"§ 1"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"codeBodyId","in":"query","required":true,"description":"UUID of the code body (from /api/v1/code-bodies).","schema":{"type":"string"}},{"name":"parent","in":"query","required":false,"description":"Optional parent node UUID; omit for top-level.","schema":{"type":"string"}}],"security":[{"bearerAuth":["browse"]}]}},"/api/v1/gis/{shortCode}":{"get":{"operationId":"getGisLayer","summary":"Zoning layer (GeoJSON) for a city","description":"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. (Costs 5 credits.)","tags":["GIS"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"shortCode":"CA-SF","status":"published","citationQuality":"linked","featureCount":76,"geojson":"FeatureCollection"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"shortCode","in":"path","required":true,"description":"Municipal jurisdiction short code.","schema":{"type":"string","example":"CA-SF"}}],"security":[{"bearerAuth":["gis"]}]}},"/api/v1/coverage":{"get":{"operationId":"getCoverage","summary":"What law is available right now","description":"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. (Costs 1 credit.)","tags":["Coverage"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"totalJurisdictions":16,"totalNodes":384890,"totalSearchableChunks":678366,"publishedGisLayers":8,"jurisdictions":[{"shortCode":"TX","name":"Texas","level":"state","nodeCount":125188,"searchableChunks":79222,"placeholder":false}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"bearerAuth":["search","node","browse","gis"]}]}},"/api/v1/me":{"get":{"operationId":"getAccount","summary":"Your key's credits + usage","description":"Live credit balance, tier, rate limits, recent ledger entries, and upgrade options with prices. The budget-introspection endpoint for agents. (Costs 1 credit.)","tags":["Account"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"tier":"free","creditsRemaining":87,"rateLimit":{"requestsPerMinute":10,"requestsPerDay":100},"upgradeOptions":[{"pack":"starter","priceCents":500,"credits":1000}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"bearerAuth":["search","node","browse","gis","formation"]}]}},"/api/v1/formation/status/{orderId}":{"get":{"operationId":"getFormationStatus","summary":"Track a formation order","description":"Status of an LLC/nonprofit formation order. Requires the per-order tracking token issued when the order was created. (Costs 1 credit.)","tags":["Formation"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"orderId":"uuid","state":"filed","entityName":"Acme LLC"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"orderId","in":"path","required":true,"description":"Formation order UUID.","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"Per-order tracking token.","schema":{"type":"string"}}],"security":[{"bearerAuth":["formation"]}]}},"/api/v1/compare/llc-services":{"get":{"operationId":"compareLlcServices","summary":"LLC formation provider comparison dataset","description":"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.","tags":["General"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"dataset":"corpus-llc-formation-competitive-intelligence","research_verified":"2026-09-04","disclosure":"Corpus publishes this dataset and is one of the providers in it.","companies":[{"slug":"corpus","agentic_readiness":86,"ra_renewal":"$99/yr"}]}}}}}}}},"/api/v1/formation/prices":{"get":{"operationId":"formationPriceGrid","summary":"Corpus formation price grid, every state","description":"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.","tags":["Formation"],"responses":{"200":{"description":"Success","headers":{"X-Credits-Remaining":{"$ref":"#/components/headers/XCreditsRemaining"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"}},"content":{"application/json":{"schema":{"type":"object","example":{"llc":[{"code":"MS","stateFeeCents":5400,"registeredAgentCents":10000,"corpusMarginCents":9600,"totalCents":25000}],"nonprofitCorp":"same shape","nonprofitUnavailable":["NH","NY"],"registeredAgentRenewalUsdPerYear":99,"einAddon":{"cents":7500,"available":false}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your key as `Authorization: Bearer <api_key>`. Header only — query-param auth is disabled in production."}},"headers":{"XCreditsRemaining":{"description":"Credits left on this key after the call.","schema":{"type":"integer"}},"XRateLimitLimit":{"description":"Requests-per-minute ceiling for this key's tier.","schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable error code.","example":"insufficient_credits"},"message":{"type":"string","description":"Human-readable explanation with a recovery hint."},"upgradeUrl":{"type":"string","description":"Where to buy more credits (present on 402)."},"retryAfterSec":{"type":"integer","description":"Seconds to wait before retrying (present on 429)."}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"A valid API key is required. Pass it via the Authorization: Bearer <key> header."}}}},"Forbidden":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"insufficient_scope","message":"This key does not have any of the required scopes."}}}},"InsufficientCredits":{"description":"No credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"insufficient_credits","message":"You have no credits remaining. Buy credits to continue.","upgradeUrl":"https://corpuslaw.us/api/v1/billing/checkout"}}}},"RateLimited":{"description":"Rate limit exceeded. Respect `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Rate limit exceeded. Try again in 60 seconds.","retryAfterSec":60}}}},"ValidationError":{"description":"A required parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"The 'q' parameter is required."}}}}}}}