Cases API

HTTP endpoints for case-law research: court opinions, courts, and search.

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.

GET /me also supports OAuth access tokens via Authorization: Bearer <access_token>.

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
`/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)
`/me`	GET	Retrieve the authenticated user ID and subscription status

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)

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.

These rules apply to /opinions/get. /search results are built from the search index and do not include per_curiam or en_banc.

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

Current User Endpoint

Use GET /me to fetch the authenticated user's Midpage user ID and subscription status.

Response

{
  "userId": "user_123",
  "subscriptionStatus": "active"
}

Common subscriptionStatus values:

active
trialing
past_due
canceled

See the API Reference tab for complete endpoint documentation, request/response schemas, and interactive examples.

MCP Changelog

Laws API

Cases API

Base URL

Authentication

Endpoints

Search Endpoint

Semantic Search (default)

Keyword Search

Boolean Operators

Hybrid Search

Available Filters

Reranking

Facets (Result Breakdowns)

Response

Opinions Endpoint

By Opinion IDs

By Citation

By Docket Number

Request Parameters

Response

Court Endpoint

Request

Response

Court List Endpoint

Response

Current User Endpoint

Response