Caselaw API · Federal & state opinions · REST
The caselaw API builders want is simple to describe and hard to operate: boolean and semantic search across federal and state opinions, reliable retrieval by cite or id, full text and PDF, and treatment signals you can show in a product UI. That is what LawDiver ships.
LawDiver’s caselaw API is a REST surface over more than 10 million U.S. court opinions with about 100 million citation edges and 190 million in-text citations with pin offsets. Authenticate once; call search, retrieve, text, PDF, good-law, cited-by, and cite-check without a separate enterprise negotiation for primary-law access during the rollout.
| Endpoint shape | What it does |
|---|---|
| POST /api/v1/search | Boolean, semantic, hybrid, citation, name, or auto — with jurisdiction filters. |
| POST /api/v1/citations/resolve | Resolve a cite or case name to candidates (free permanently). |
| POST /api/v1/cases/retrieve | Cite or name in, case out — with did-you-mean when ambiguous. |
| POST /api/v1/cases/batch | Up to 50 case lookups in one round trip. |
| GET /api/v1/cases/:id/text | Full opinion text as JSON. |
| GET /api/v1/cases/:id/pdf | Opinion PDF. |
| GET /api/v1/cases/:id/good-law | Good-law status and negative treatment. |
| GET /api/v1/cases/:id/cited-by | Everything citing this case, paginated. |
| POST /api/v1/citecheck/cite | Check one citation, or up to 50 at once. |
| POST /api/v1/citecheck/document | Upload a PDF or Word brief; check every cite in it. |
| GET /api/v1/jurisdictions | Jurisdiction codes search accepts. |
| GET /api/v1/usage | Your usage and spend to date. |
Every response carries a requestId. Billable responses include a usage block. Rate-limit headers ship on every authenticated call. Idempotency-Key is honored on billable POSTs so a retried request replays the original answer instead of re-running the work.
Search phrases like caselaw API and case law API almost always mean: give my app opinions as data. HTML pages and quarterly bulk tarballs are not enough when a user is typing in your UI. You need live search, stable ids, and retrieval that does not collapse under product traffic.
Free Law Project / CourtListener bulk dumps and the Harvard Caselaw Access Project seeded much of this field — LawDiver accounts for that provenance on Licenses. A dump is a snapshot. A caselaw API is the continuously harvested, queryable service your product hits on every request, with commercial licensing published up front.
The hardest part of legal retrieval is that “search” is not one operation. A lawyer types five fundamentally different things into the same box: a reporter citation with exactly one right answer; a case name that may be misspelled; a boolean query with a proximity connector; a concept phrased as a question using none of the words the opinion uses; or all of those at once. Systems that treat these as one problem are bad at all five.
LawDiver’s search router extracts every signal at once and produces a plan — reporter citations, docket numbers, an X v. Y caption, the parsed boolean expression, jurisdiction phrases lifted into filters, and residual concept text — instead of stamping the query with a single label and discarding the rest. Constraints become filters and never search terms: leave “5th Circuit” in the query text and you get opinions that discuss the Fifth Circuit; lift it into a filter and it removes most of the corpus before expensive work runs.
searchType accepts auto (default — the router picks, and what the LawDiver UI runs), citation (exact reporter-key lookup), case_name (trigram-indexed names so misspellings still land), keyword (boolean, phrase, and proximity over a Lucene index with BM25 ranking), semantic (meaning-space retrieval), and hybrid (keyword and semantic fused). Pinning is honest: if you pin citation on a query with no citation in it, the API tells you the engine was dropped for want of usable input — rather than returning an empty set that looks like “this case does not exist.”
For agent loops, turn on include so one search call returns what the model needs without a round trip per hit: caseCard (summary, holdings, issues, quotations when Stage-2 analysis exists), opinionText (full text under a character budget, otherwise query-relevant excerpts), and goodLawReport (expands good-law with negative citing cases — on by default so treatment is never a follow-up guess).
Uppercase AND, OR, and NOT are operators. Lowercase and is a word, because trust and estate is a phrase a lawyer types in lowercase and means literally. Quoted runs stay intact. Westlaw-style proximity connectors work: /s (same sentence), /p (same paragraph), and /3 or w/3 (within n words, either order).
Postgres full-text search cannot express “same sentence” or “same paragraph.” Encoding /s as “within 10 words” returns confidently wrong results — the worst failure mode in a research tool. LawDiver splits the work: the inverted index does recall, and proximity is verified in code against candidate text sentence by sentence and paragraph by paragraph, so /s means what a lawyer means by /s.
Embeddings are Qwen3-Embedding-8B at 1024 dimensions, stored as half-precision pgvector values and retrieved through a binary-quantized HNSW index — a fast Hamming first pass, then a full-precision rerank. Cosine similarity compares angle, not length, so a short holding and a long opinion can still be “about the same thing.”
Two different things are embedded. One set embeds the opinion’s own body. The other embeds model-authored analysis of the opinion — issue, holding, posture, disposition. A question phrased the way a lawyer would ask it matches the analysis set; the body set catches what the analysis omitted. Search covers both, so recall is the union.
Keyword and semantic scores are convex-combined with eligibility renormalization; citation and name hits act as lookup overrides rather than fusion participants, because an exact reporter-key match is proof, not an estimate. Jurisdiction is required on every search — an unscoped national query is the slowest thing the stack can run and almost never what the caller meant. Eight published choices cover what lawyers actually pick: all states, all states plus federal, all federal, one state, one state plus federal, a named circuit, federal district, or the U.S. Supreme Court alone. Filters run inside every engine query: date range, published-only, include-unpublished, good-law-only.
Two defaults are deliberate mirrors. Unpublished opinions are hidden by default, because in most jurisdictions they cannot be cited as precedent; one flag brings them back. Bad law is never hidden by default — an overruled case is still the case the researcher went looking for, flagged rather than suppressed. Every result carries good-law status inline, including a separate unknown flag so software cannot mistake silence for approval, plus a snippet, a plain-English matchExplanation, and a retrieval URL for the full PDF.
Search is billed per case returned, not per search. An empty result set is free. Enrichment does not change the per-case price.
Returning the opinion text without treatment leaves the hard problem to the caller. LawDiver exposes good-law and citing-opinion routes so a product can show whether an authority is still reliable — with an explicit unknown distinct from negative, so software cannot treat a missing determination as a cleared one.
A hallucinated citation looks exactly like a real one. The useful question is whether the string names a real case in a corpus LawDiver holds, what its correct Bluebook form is, and whether it is still good law. POST /api/v1/citecheck/cite returns a verdict taxonomy that refuses to silently correct an ambiguous cite: exact matches require both reporter key and agreeing caption, year, and court; a real reporter key glued to the wrong caption is never reported as valid; likely matches return ranked candidates without picking one for you. Failed checks are emitted as full rows and are not billed. Upload a PDF or Word brief to POST /api/v1/citecheck/document for document-scale checking; short forms bind to earlier full cites in the same filing rather than being re-resolved as first pages. Field-level detail lives in the API docs and on the CiteCheck product page.
Authenticate with Authorization: Bearer or X-API-Key. One gate handles authentication, rate limiting, and request-id assignment for every route. Errors use a typed taxonomy — missing or invalid key, account suspended, rate limited, invalid request with field-by-field detail, service unavailable, internal error — each carrying the requestId you can quote to support. Billing when charged is per case returned on search and per citation on cite-check, with errors excluded; GET /api/v1/usage shows calls, units, and cost by operation. Right now the API is free during the current rollout; usage is still recorded, and if that changes the unauthenticated discovery document at GET /api/v1 and the docs will say so first.
Public response shapes are deliberately narrower than internal ones. Fusion scores and per-engine ranks stay unpublished so ranking can improve without freezing an implementation into your contract. What is published is additive-only: fields get added, never renamed out from under you.
Create an account, mint a key, and follow the runnable examples on /docs/api. The same key works with MCP connectors for Claude, ChatGPT, and Cursor. For the broader legal research API — statutes, regulations, and commercial licensing — see the API product page.
curl -X POST https://lawdiver.com/api/v1/search \
-H "Authorization: Bearer $LAWDIVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "\"qualified immunity\" AND \"clearly established\"", \
"jurisdiction": { "type": "all_federal" }, "searchType": "keyword", "limit": 10}'Free during the current rollout. Docs at /docs/api.