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
}

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"]
    }
  }
}

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 semantic mode (Pinecone doesn't support aggregations)
  • In hybrid mode, facet counts reflect keyword search results only; semantic (Pinecone) results are not included in these counts. A note field will be present explaining this limitation.
  • Each result includes a source field indicating where it came from. In semantic and keyword modes it's constant; in hybrid mode 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.