Cases API
HTTP endpoints for case-law research: court opinions, courts, search, dockets, and filings.
One API covers both case law and laws (statutes, regulations, constitutions, agency guidance). The base URL and authentication below apply to all of it; the laws endpoints are documented in Laws API.
Base URL
https://app.midpage.ai/api/v1
Authentication
Create and manage API keys in the API dashboard. If you need help setting up an organization eligible for API keys, contact support@midpage.ai.
Endpoints
| Endpoint | Method | Description |
|---|---|---|
/search |
POST | Search for opinions using semantic, keyword, or hybrid search |
/opinions/get |
POST | Retrieve full opinion data by ID, citation, or docket |
/court/get |
POST | Look up court metadata by ID, abbreviation, or name |
/court/list |
GET | List every available court and its ID |
/dockets/get |
POST | [preview] Retrieve a docket and its entries |
/filings/get |
POST | [preview] Retrieve one filing's text and file |
/laws/search |
POST | Search statutes, regulations, constitutions, and guidance |
/laws/get |
POST | Retrieve one law document by citation, register citation, path, or id |
/laws/collections |
GET | List available law collections (codes/registers) |
Search Endpoint
The /search endpoint supports three search modes:
Semantic Search (default)
Vector similarity search using AI embeddings. Best for conceptual queries.
{
"query": "breach of fiduciary duty",
"mode": "semantic",
"page": 1,
"page_size": 10
}
Keyword Search
Traditional full-text search. Best for exact phrases and known terms. Supports Lexis/Westlaw-style boolean operators.
{
"query": "summary judgment standard",
"mode": "keyword",
"page": 1,
"page_size": 20,
"filters": {
"jurisdictions": ["Federal Appellate"],
"publish_status": "published",
"date_filed": {
"start": "2020-01-01",
"end": "2024-12-31"
}
}
}
Boolean Operators
Keyword mode supports Lexis/Westlaw-style boolean operators:
| Operator | Description | Example |
|---|---|---|
AND |
Both terms must appear | negligence AND damages |
OR |
Either term may appear | breach OR default |
NOT |
Exclude term | contract NOT employment |
"..." |
Exact phrase | "summary judgment" |
* |
Wildcard (any characters) | negligen* |
? |
Single character wildcard | wom?n |
W/n |
Within n words (proximity) | negligence W/5 damages |
() |
Grouping | (contract OR agreement) AND breach |
Important: Boolean operators must be UPPERCASE (e.g., AND not and).
Example: Boolean search
{
"query": "(contract OR agreement) AND breach NOT employment",
"mode": "keyword",
"page": 1,
"page_size": 20
}
Example: Proximity search
{
"query": "negligence W/5 damages",
"mode": "keyword",
"page": 1,
"page_size": 20
}
When boolean operators are detected, the response includes a boolean_query field in metadata:
{
"metadata": {
"mode": "keyword",
"query": "negligence AND damages",
"processing_time_ms": 459,
"boolean_query": {
"detected": true,
"operators": ["AND"]
}
}
}
Hybrid Search
Combines semantic and keyword results using reciprocal rank fusion (RRF) with deduplication. Best for comprehensive coverage.
{
"query": "fourth amendment search and seizure",
"mode": "hybrid",
"page": 1,
"page_size": 10,
"filters": {
"court_ids": ["ca9", "scotus"]
}
}
Available Filters
| Filter | Type | Description |
|---|---|---|
court_ids |
string[] | Court identifiers (e.g., ["ca9", "scotus"]) |
jurisdictions |
string[] | Jurisdiction types (e.g., ["Federal Appellate"]) |
states |
string[] | State names (e.g., ["California"]) |
publish_status |
string | Publication status: published, unpublished, unknown, in_chambers, separate, errata, or relating_to |
date_filed.start |
string | Start date (YYYY-MM-DD) |
date_filed.end |
string | End date (YYYY-MM-DD) |
Use publish_status: "unknown" to include opinions where publication metadata is missing or uncertain.
Reranking
Enable AI-powered reranking to improve result relevance using Cohere's rerank model. When enabled, the API fetches more candidates internally and reranks them for better precision.
{
"query": "summary judgment standard",
"mode": "keyword",
"rerank": true,
"page_size": 10
}
Response with reranking:
{
"results": [...],
"metadata": {
"mode": "keyword",
"query": "summary judgment standard",
"processing_time_ms": 4328,
"rerank": {
"enabled": true,
"rerank_time_ms": 344
}
}
}
Notes:
- Reranking adds latency but significantly improves relevance
- Cannot be used with
page > 1(reranking only applies to first page) - Works with all search modes (semantic, keyword, hybrid)
Facets (Result Breakdowns)
For keyword and hybrid modes, the response can include facet breakdowns showing result counts by court, jurisdiction, state, and year when include_facets: true is set. This is useful for building filter UIs or understanding result distribution.
Facet counts are computed across the full result set (after filters), not just the current page.
To enable facets, set include_facets: true:
{
"query": "copyright infringement",
"mode": "keyword",
"include_facets": true
}
Response with facets (when enabled):
{
"results": [...],
"pagination": {...},
"facets": {
"court_abbreviation": [
{ "key": "9th Cir.", "count": 1523 },
{ "key": "S.D.N.Y.", "count": 892 }
],
"jurisdiction": [
{ "key": "Federal Appellate", "count": 3200 },
{ "key": "Federal District", "count": 4100 }
],
"state": [
{ "key": "California", "count": 1800 },
{ "key": "New York", "count": 1650 }
],
"year_filed": [
{ "key": "2024", "count": 1200 },
{ "key": "2023", "count": 2100 }
]
}
}
Important notes:
- Facets are disabled by default and only included when
include_facets: true - Facets are not available in
semanticmode (Pinecone doesn't support aggregations) - In
hybridmode, facet counts reflect keyword search results only; semantic (Pinecone) results are not included in these counts. Anotefield will be present explaining this limitation. - Each result includes a
sourcefield indicating where it came from. Insemanticandkeywordmodes it's constant; inhybridmode it varies per item.
Response
Examples below are real responses with snippets truncated for brevity.
Semantic mode response (no facets):
{
"results": [
{
"opinion_id": "8515707",
"score": 0.721916258,
"case_name": "Myer v. Preferred Credit, Inc.",
"midpage_url": "https://app.midpage.ai/document/myer-v-preferred-credit-inc-8515707",
"court_id": "ohctcomplharris",
"court_name": "Harrison County Court of Common Pleas",
"jurisdiction": "State Trial",
"state": "Arizona",
"date_filed": null,
"snippet": "As such, it is a successor-in-interest, and may be liable on the claims herein...",
"source": "semantic"
}
],
"pagination": {
"page": 1,
"page_size": 1,
"total_results": 3,
"total_pages": 3,
"has_next": true,
"has_prev": false
},
"metadata": {
"mode": "semantic",
"query": "breach of fiduciary duty",
"processing_time_ms": 182
}
}
Keyword mode response (facets included by default):
{
"results": [
{
"opinion_id": "1000460566592",
"score": 61.955864,
"case_name": "In Re: OpenAI, Inc. Copyright Infringement Litigation",
"midpage_url": "https://app.midpage.ai/document/in-re-openai-inc-copyright-1000460566592",
"court_id": "nysd",
"court_name": "District Court, S.D. New York",
"court_abbreviation": "S.D.N.Y.",
"jurisdiction": "Federal District",
"state": "New York",
"publish_status": "published",
"date_filed": "2025-12-02",
"docket_number": "1:23-cv-11195",
"snippet": "INFRINGEMENT LITIGATION, ...",
"source": "keyword"
}
],
"pagination": {
"page": 1,
"page_size": 1,
"total_results": 10000,
"total_pages": 10000,
"has_next": true,
"has_prev": false
},
"metadata": {
"mode": "keyword",
"query": "copyright infringement",
"processing_time_ms": 189
},
"facets": {
"court_abbreviation": [
{ "key": "S.D.N.Y.", "count": 11657 },
{ "key": "N.D. Cal.", "count": 7993 }
],
"jurisdiction": [
{ "key": "Federal District", "count": 127544 },
{ "key": "Federal Appellate", "count": 45956 }
],
"state": [
{ "key": "Federal", "count": 56818 },
{ "key": "California", "count": 19113 }
],
"year_filed": [
{ "key": "1786", "count": 1 },
{ "key": "1789", "count": 1 }
]
}
}
Hybrid mode response (mixed sources; facets include note):
{
"results": [
{
"opinion_id": "8515707",
"score": 0.721916258,
"case_name": "Myer v. Preferred Credit, Inc.",
"midpage_url": "https://app.midpage.ai/document/myer-v-preferred-credit-inc-8515707",
"court_id": "ohctcomplharris",
"court_name": "Harrison County Court of Common Pleas",
"jurisdiction": "State Trial",
"state": "Arizona",
"date_filed": null,
"snippet": "As such, it is a successor-in-interest, and may be liable on the claims herein...",
"source": "semantic"
},
{
"opinion_id": "10612453",
"score": 35.931553,
"case_name": "Salvatoriello v. Coady",
"midpage_url": "https://app.midpage.ai/document/salvatoriello-v-coady-10612453",
"court_id": "nysupctkings",
"court_name": "New York Supreme Court, Kings County",
"jurisdiction": "State Trial",
"state": "New York",
"date_filed": "2024-10-08",
"snippet": "The verifj_ed amended_ complaint asserts causes of action for breach of fiduciary duty...",
"source": "keyword"
}
],
"pagination": {
"page": 1,
"page_size": 2,
"total_results": 10000,
"total_pages": 5000,
"has_next": true,
"has_prev": false
},
"metadata": {
"mode": "hybrid",
"query": "breach of fiduciary duty",
"processing_time_ms": 196
},
"facets": {
"court_abbreviation": [
{ "key": "N.Y. App. Div.", "count": 77644 },
{ "key": "Cal. Ct. App.", "count": 63785 }
],
"jurisdiction": [
{ "key": "Federal District", "count": 828389 },
{ "key": "State Appellate", "count": 762503 }
],
"state": [
{ "key": "Federal", "count": 445751 },
{ "key": "New York", "count": 177305 }
],
"year_filed": [
{ "key": "1700", "count": 2 },
{ "key": "1701", "count": 1 }
],
"note": "Facet counts reflect keyword search results only; semantic (Pinecone) results are not included in these counts."
}
}
Each search result includes midpage_url, the canonical public Midpage opinion page. Use this URL for links shown to end users; do not construct a /document/{opinion_id} URL, because bare opinion-ID pages are not public.
Opinions Endpoint
The /opinions/get endpoint retrieves full opinion data. Provide exactly one of: opinion_ids, citations, or docket.
By Opinion IDs
{
"opinion_ids": ["108713", "4976599"],
"include_content": true,
"include_detailed_treatments": false
}
By Citation
{
"citations": ["410 U.S. 113", "93 S. Ct. 705"]
}
By Docket Number
Requires court context (either court_id or court_abbreviation):
{
"docket": {
"docket_number": "70-18",
"court_abbreviation": "SCOTUS"
}
}
Request Parameters
| Parameter | Type | Description |
|---|---|---|
opinion_ids |
string[] | Opinion IDs to retrieve (max 100) |
citations |
string[] | Citations to look up (max 100) |
docket |
object | Docket lookup with docket_number and court_id or court_abbreviation |
include_content |
boolean | Include full HTML opinion text (default: false) |
include_detailed_treatments |
boolean | Include citing opinions with treatment analysis (default: false) |
Response
{
"opinions": [
{
"id": "108713",
"case_name": "Roe v. Wade",
"midpage_url": "https://app.midpage.ai/document/roe-v-wade-108713",
"court_id": "scotus",
"court_abbreviation": "SCOTUS",
"docket_number": "70-18",
"state": "Federal",
"publish_status": "published",
"date_filed": "1973-01-22",
"judge_name": "Blackmun",
"citations": [
{ "cited_as": "410 U.S. 113", "volume": "410", "reporter": "U.S.", "page": "113" }
],
"pagination_citation": "410 U.S. 113",
"citation_count": 4603,
"overall_treatment": "Negative",
"html_content": "...",
"treatments": [
{
"citing_id": "12345",
"treatment_category": "Negative",
"treatment_description": "Overruled by...",
"is_authoritative": true,
"supporting_quote": "..."
}
]
}
],
"citation_matches": [
{ "citation": "410 U.S. 113", "opinion_id": "108713" }
]
}
Every returned opinion includes midpage_url, the canonical public Midpage opinion page suitable for sharing with unauthenticated users.
pagination_citation names the citation whose page numbers the <midpage-ps> page markers in html_content follow. An opinion often has several citations, but its text usually carries the page breaks of only one reporter, so use this citation when building pinpoint citations. It is null when the text has no reporter page markers or the reporter cannot be established; cite without a pinpoint page then. It is returned whether or not include_content is set. See Page Numbers.
case_name is the opinion's short title when the document carries one, otherwise the docket caption. For example, the caption "Lydia Tummel v. Robert Milane" is returned as "Tummel v. Milane". The midpage_url slug is always built from the docket caption, so it can differ from case_name.
judge_name lists every known judge on the opinion, comma-separated (for example "KING, JONES, DENNIS"). It is always returned, and is null when no judge is known.
per_curiam and en_banc appear only when they are true. When an opinion is not per curiam, or that is unknown, the key is absent; it is never false or null. en_banc works the same way.
precedential_note is the court's own limiting caveat printed on the opinion, verbatim. It is either a publication or precedential limit, such as "NOT FOR PUBLICATION" or a court rule stating that the opinion is not precedent, or a finality caveat, such as "not final until disposition of any timely motion for rehearing". Several caveats are joined with " | ". Positive designations such as "FOR PUBLICATION" are never included. It is independent of publish_status.
A missing precedential_note does not prove the opinion prints no caveat. Coverage is incomplete: some older opinions were never checked for one, and some carry only their strongest caveat, shortened. Use publish_status for the publication decision.
These rules apply to /opinions/get. /search results are built from the search index and do not include per_curiam, en_banc, or precedential_note.
Court Endpoint
The /court/get endpoint retrieves court metadata. Provide exactly one of: court_ids, court_abbreviations, or names.
Request
{
"court_abbreviations": ["SCOTUS", "9th Cir."]
}
Response
{
"courts": [
{
"id": "scotus",
"full_name": "Supreme Court of the United States",
"court_abbreviation": "SCOTUS",
"jurisdiction": "Federal Appellate",
"state": "Federal",
"in_use": true,
"pacer_court_id": null
},
{
"id": "ca9",
"full_name": "Court of Appeals for the Ninth Circuit",
"court_abbreviation": "9th Cir.",
"jurisdiction": "Federal Appellate",
"state": "Federal",
"in_use": true,
"pacer_court_id": "9"
}
]
}
Court List Endpoint
GET /court/list returns every court available through the API, with the same fields as /court/get. It takes no parameters. Use it to find the IDs that the court_ids search filter accepts, and to see when courts are added.
in_use is false for historical courts, such as courts that were renamed, merged, or abolished, and true for current courts. Opinions from historical courts remain available.
Response
{
"courts": [
{
"id": "nlrb",
"full_name": "National Labor Relations Board",
"court_abbreviation": "NLRB",
"jurisdiction": "Federal Special",
"state": "Federal",
"in_use": true,
"pacer_court_id": null
},
{
"id": "ccpa",
"full_name": "Court of Customs and Patent Appeals",
"court_abbreviation": "C.C.P.A.",
"jurisdiction": "Federal Special",
"state": "Federal",
"in_use": false,
"pacer_court_id": null
}
]
}
Dockets and filings [preview]
These endpoints use the same base URL and API key.
Read the federal and state court dockets and filings we hold, and fetch federal ones we don't hold from PACER.
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/dockets/get |
POST | A docket: case details, parties and entries |
/api/v1/filings/get |
POST | One filing: its text and a link to the file |
PACER balance
Dockets and filings served from storage are free. For a federal docket or filing we don't have, or a fresher copy asked for with max_age_hours, we may fetch it from PACER. PACER fetches are paid from your organization's prepaid PACER balance, at PACER's fee with no markup.
- Org admins top up the balance from the Billing tab of the developer portal. The minimum top-up is $50.
- When the balance is too low for a fetch, the request answers
402 pacer_balance_insufficient.
Successful responses include cost. Some error responses include it too:
"cost": { "pacer_cents": 30, "pacer_pages": 3, "balance_cents": 46970 }
pacer_cents is what this request was charged, pacer_pages the pages PACER billed, and balance_cents your available balance after it. pacer_pages and balance_cents can be null when unavailable. Authentication, validation, and other early errors can omit cost.
Before a purchase, your available balance must cover a hold of $3.00 for a district or bankruptcy docket, $3.50 for an appellate docket, $6.00 for an appellate filing, or the quoted fee for a district or bankruptcy filing. The final charge is PACER's fee, capped at the hold.
A filing request can first buy a docket. If that succeeds but the filing cannot be returned, the docket remains available and charged, including on a 402 or 502 response. Always check cost when handling an error. Retrying max_age_hours: 0 can buy another refresh; these endpoints do not accept an idempotency key.
Get a docket
POST /api/v1/dockets/get
{
"docket": { "docket_number": "1:24-cv-00533", "court_id": "nysd" },
"max_age_hours": 24
}
| Parameter | Type | Description |
|---|---|---|
case_id |
string | A docket's case_id. Send this or docket |
docket.docket_number |
string | The court's docket number |
docket.court_id |
string | Court ID, such as nysd. Or send docket.court_abbreviation |
docket.case_name |
string | Optional. Picks one docket when several share the number |
max_age_hours |
integer | Optional, 0 or greater. At courts PACER serves, fetch again if our copy is older than this many hours. 0 always fetches on the first page. Omit to accept any held copy |
limit |
integer | Entries per page, 1 to 1000. Default 1000 |
cursor |
string | next_cursor from the previous page. Repeat the original case_id or docket lookup |
At courts PACER does not serve, max_age_hours is ignored; fetched_at gives the copy's age when known. Cursor pages are free and do not refresh the docket. Keep using the original lookup when paging, even if the response returns a different case_id.
Response excerpt:
{
"docket": {
"case_id": "5c1f9e2a-7d43-4b8e-9a61-2f0c8d3e4b17",
"case_name": "Doe v. Acme Corp.",
"court_id": "nysd",
"docket_number": "1:24-cv-00533",
"date_filed": "2024-01-24",
"parties": [{ "name": "Acme Corp.", "role": "Defendant", "attorneys": [] }],
"fetched_at": "2026-10-14T13:02:11.000Z",
"entry_count": 1
},
"entries": [
{
"filing_id": "c9f1a2b3-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"entry_number": "42",
"date_filed": "2026-09-30",
"description": "MOTION to Dismiss for Lack of Jurisdiction",
"document": "purchasable",
"attachments": []
}
],
"next_cursor": null,
"cost": { "pacer_cents": 30, "pacer_pages": 3, "balance_cents": 46970 }
}
Each entry's document is stored (free from filings/get), purchasable (can be fetched from PACER with access enabled) or none. Attachments have their own filing_id. On appellate dockets, entry_number can be null; use filing_id instead. The API Reference lists every field.
Get a filing
POST /api/v1/filings/get. Send case_id and one of filing_id or entry_number.
{ "case_id": "5c1f9e2a-7d43-4b8e-9a61-2f0c8d3e4b17", "filing_id": "c9f1a2b3-4d5e-4f60-8a7b-9c0d1e2f3a4b" }
| Parameter | Type | Description |
|---|---|---|
case_id |
string | The docket's case_id |
filing_id |
string | An entry's or attachment's filing_id from dockets/get |
entry_number |
string | The entry number as printed, such as "42" |
attachment_number |
string | Optional, with entry_number. "1" for ECF No. 42-1 |
Entry and attachment numbers are strings, such as "42" and "1".
Response excerpt:
{
"filing": {
"filing_id": "c9f1a2b3-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"case_id": "5c1f9e2a-7d43-4b8e-9a61-2f0c8d3e4b17",
"entry_number": "42",
"description": "MOTION to Dismiss for Lack of Jurisdiction",
"content_type": "application/pdf",
"file_url": "https://app.midpage.ai/api/case/5c1f9e2a-7d43-4b8e-9a61-2f0c8d3e4b17/docket/c9f1a2b3-4d5e-4f60-8a7b-9c0d1e2f3a4b/raw",
"text": "UNITED STATES DISTRICT COURT\nSOUTHERN DISTRICT OF NEW YORK\n..."
},
"cost": { "pacer_cents": 40, "pacer_pages": 4, "balance_cents": 46930 }
}
text, file_url, and occasionally filing_id can be null when unavailable, even after a successful purchase. A missing field value does not reverse the charge.
Docket and filing errors
Errors carry error and code, and usually a message for people. Branch on code. Both endpoints share a rate of 30 requests per minute per organization, across all its keys.
| Status | code |
When |
|---|---|---|
| 400 | invalid_request |
The request isn't valid |
| 401 | unauthorized |
The API key is missing or invalid |
| 402 | pacer_balance_insufficient |
The PACER balance is too low for this fetch |
| 403 | pacer_not_enabled |
This API key can't use these endpoints |
| 403 | filing_restricted |
The court restricts access to this document |
| 404 | docket_not_found, filing_not_found, no_document |
No such docket or filing, or no document we can return |
| 409 | ambiguous_docket |
Several dockets share this number. Resend with a candidate's case_id, or docket.case_name |
| 409 | ambiguous_filing |
Several entries print this number. Use filing_id |
| 422 | unsupported_court |
We don't know this court |
| 429 | too_many_requests |
More than 30 requests a minute. Wait the seconds in Retry-After |
| 500 | internal_error |
An error on our side |
| 502 | pacer_unavailable |
PACER or the court didn't answer. Try again later |
| 503 | service_unavailable |
Briefly unavailable. Wait the seconds in Retry-After |
See the API Reference tab for complete endpoint documentation, request/response schemas, and interactive examples.