Integration

REST API

HTTP endpoints for searching and retrieving legal content.

Note: The REST API currently supports court opinions. Statute and regulation endpoints are coming soon. For immediate access to statutes and regulations, use SQL direct access or the MCP tools.

Base URL 

http://app.midpage.ai/api/v1

Authentication

Get an API key at http://app.midpage.ai/api/v1. 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

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"],
    "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 50/50 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"])
date_filed.start string Start date (YYYY-MM-DD)
date_filed.end string End date (YYYY-MM-DD)

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 automatically includes facet breakdowns showing result counts by court, jurisdiction, state, and year. 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 disable facets, set include_facets: false:

{
  "query": "copyright infringement",
  "mode": "keyword",
  "include_facets": false
}

Response with facets (default for keyword/hybrid):

{
  "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 enabled by default for keyword and hybrid modes
  • 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.",
      "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",
      "court_id": "nysd",
      "court_name": "District Court, S.D. New York",
      "jurisdiction": "Federal District",
      "state": "New York",
      "date_filed": "2025-12-02",
      "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.",
      "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",
      "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."
  }
}

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",
      "court_id": "scotus",
      "court_abbreviation": "SCOTUS",
      "docket_number": "70-18",
      "state": "Federal",
      "date_filed": "1973-01-22",
      "judge_name": "Blackmun",
      "citations": [
        { "cited_as": "410 U.S. 113", "volume": "410", "reporter": "U.S.", "page": "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" }
  ]
}

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

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

Previous
MCP Tools
Next
Schema