{"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"]}]}}},"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."}}}}}}}