Vector similarity search over court opinions using AI embeddings, ranking results by semantic similarity for conceptual queries. Exposed as the `semantic` mode of the POST /search endpoint and combined with keyword search in `hybrid` mode.
openapi: 3.0.1
info:
title: Midpage Legal Database API
description: >-
REST API for Midpage's US legal database ("Caselaw Building Blocks"). Search
court opinions with semantic (vector), keyword (full-text), or hybrid search;
retrieve full opinion data by ID, citation, or docket number with citator
treatments; and read the authenticated user's identity and subscription
status. Authenticate with a bearer token (API key) in the Authorization header.
termsOfService: https://www.midpage.ai/
contact:
name: Midpage
url: https://www.midpage.ai/
version: '1.0'
servers:
- url: https://app.midpage.ai/api/v1
description: Production server
security:
- apiKey: []
paths:
/search:
post:
operationId: searchOpinions
tags:
- Search
summary: Search opinions
description: >-
Search for opinions using semantic (vector), keyword (full-text), or
hybrid search.
Search modes: `semantic` (vector similarity using AI embeddings),
`keyword` (Elasticsearch full-text with Lexis/Westlaw-style boolean
operators), and `hybrid` (semantic + keyword combined with reciprocal
rank fusion and deduplication).
Boolean operators (keyword mode only, must be UPPERCASE): AND, OR, NOT,
"..." (exact phrase), * and ? (wildcards), W/n (proximity within n
words), and () for grouping.
Pagination uses `page` (1-indexed) and `page_size` (max 100). Semantic
search supports limited deep pagination (~500 unique results); keyword
and hybrid support deep pagination via Elasticsearch.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: query is required and must be a string
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
message:
type: string
example: Invalid API key
/opinions/get:
post:
operationId: getOpinions
tags:
- Opinions
summary: Get opinions
description: >-
Retrieve full opinion data by ID, citation, or docket number. Supports
bulk reads of up to 100 items per request. Provide exactly one of
`opinion_ids`, `citations`, or `docket` (not multiple).
Lookup methods: `opinion_ids` (direct lookup, up to 100), `citations`
(reporter citation, case-insensitive, up to 100), and `docket` (docket
number + court; single lookup, may return multiple opinions).
When using `citations` or `docket`, a lookup may match multiple opinions
(e.g., majority and dissent from the same case). The response includes
`citation_matches` or `docket_matches` arrays showing which lookups
matched which opinion IDs.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
opinion_ids:
type: array
items:
type: string
description: Array of opinion IDs to retrieve
example:
- '8623588'
- '1865773'
citations:
type: array
items:
type: string
description: Array of citation strings to look up (case-insensitive)
example:
- 556 U.S. 662
- 550 U.S. 544
docket:
$ref: '#/components/schemas/DocketLookup'
include_content:
type: boolean
default: false
description: Include full HTML content
include_detailed_treatments:
type: boolean
default: false
description: Include citator treatments
responses:
'200':
description: Opinion data
content:
application/json:
schema:
type: object
properties:
opinions:
type: array
items:
$ref: '#/components/schemas/OpinionFull'
citation_matches:
type: array
items:
$ref: '#/components/schemas/CitationMatch'
description: >-
Only present when looking up by `citations`. Shows which
citations matched which opinion IDs.
docket_matches:
type: array
items:
$ref: '#/components/schemas/DocketMatch'
description: >-
Only present when looking up by `docket`. Shows which
opinions matched.
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: >-
Must provide one of: opinion_ids, citations (as arrays), or
docket (object with docket_number)
/me:
get:
operationId: getCurrentUser
tags:
- User
summary: Get current user
description: >-
Retrieve the authenticated user's Midpage identity and current
subscription status. Authenticate with a bearer token in the
Authorization header. Supported bearer tokens: OAuth access token or API
key. Common subscription statuses: `active`, `trialing`, `past_due`,
`canceled`. If no subscription status is available, `subscriptionStatus`
may be `null`.
responses:
'200':
description: Current user profile
content:
application/json:
schema:
$ref: '#/components/schemas/CurrentUserResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: >-
API key authentication. Get your API key from the Midpage Developer
Portal at https://app.midpage.ai/developers
schemas:
CurrentUserResponse:
type: object
required:
- userId
- subscriptionStatus
properties:
userId:
type: string
description: Midpage user identifier
example: user_123
subscriptionStatus:
type: string
nullable: true
description: >-
Current subscription status. Common values include `active`,
`trialing`, `past_due`, and `canceled`. May be `null` if no
subscription status is available.
example: active
SearchRequest:
type: object
required:
- query
properties:
query:
type: string
description: Search query text
example: breach of fiduciary duty
mode:
type: string
enum:
- semantic
- keyword
- hybrid
default: semantic
description: >-
Search mode: `semantic` (vector similarity, default), `keyword`
(full-text), or `hybrid` (combined semantic and keyword results using
reciprocal rank fusion).
page:
type: integer
minimum: 1
default: 1
description: Page number (1-indexed)
page_size:
type: integer
minimum: 1
maximum: 100
default: 20
description: Results per page (max 100)
filters:
$ref: '#/components/schemas/SearchFilters'
include_facets:
type: boolean
default: false
description: >-
Include facet breakdowns in the response showing result counts by
court, jurisdiction, state, and year. Facets are only available in
`keyword` and `hybrid` modes (not `semantic`). In `hybrid` mode,
facet counts reflect keyword search results only.
SearchFilters:
type: object
description: Optional filters to narrow search results
properties:
court_ids:
type: array
items:
type: string
description: Filter by court IDs (e.g., "ca9", "scotus", "nysd")
example:
- ca9
- ca2
jurisdictions:
type: array
items:
type: string
enum:
- Federal Appellate
- Federal District
- State Supreme
- State Appellate
- State Trial
- Federal Bankruptcy
- Federal Bankruptcy Panel
- Federal Special
- Military Appellate
- State Attorney General
- State Special
- U.S. Territory
- Committee
- International
- Tribal
- Tribal Appellate
- Tribal Supreme
- Tribal Trial
description: >-
Filter by jurisdiction type using canonical values from Midpage court
metadata.
example:
- Federal Appellate
- State Supreme
states:
type: array
items:
type: string
description: >-
Filter by state using full canonical names from Midpage court
metadata.
example:
- California
- New York
publish_status:
type: string
description: >-
Filter by publication status. Use `unknown` to include opinions where
publication metadata is missing or uncertain.
enum:
- published
- unpublished
- unknown
- in_chambers
- separate
- errata
- relating_to
example: published
date_filed:
type: object
description: Filter by filing date range
properties:
start:
type: string
format: date
description: Start date (YYYY-MM-DD)
example: '2020-01-01'
end:
type: string
format: date
description: End date (YYYY-MM-DD)
example: '2024-12-31'
SearchResponse:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SearchResultItem'
pagination:
$ref: '#/components/schemas/PaginationMeta'
metadata:
type: object
properties:
mode:
type: string
enum:
- semantic
- keyword
- hybrid
description: Search mode used
query:
type: string
description: Original query
processing_time_ms:
type: integer
description: Server processing time in milliseconds
boolean_query:
type: object
description: Present in keyword mode when boolean operators are detected
properties:
detected:
type: boolean
description: Whether boolean operators were detected
operators:
type: array
items:
type: string
description: List of detected operators (e.g., ["AND", "OR", "W/5"])
facets:
$ref: '#/components/schemas/SearchFacets'
SearchFacets:
type: object
description: >-
Facet breakdowns showing result counts by various dimensions. Only
present when `include_facets: true` in request and mode is `keyword` or
`hybrid`. Counts are computed across the full result set (after filters),
not just the current page.
properties:
court_abbreviation:
type: array
items:
$ref: '#/components/schemas/FacetBucket'
description: Breakdown by court abbreviation (e.g., "9th Cir.", "S.D.N.Y.")
jurisdiction:
type: array
items:
$ref: '#/components/schemas/FacetBucket'
description: Breakdown by jurisdiction type
state:
type: array
items:
$ref: '#/components/schemas/FacetBucket'
description: Breakdown by state name
year_filed:
type: array
items:
$ref: '#/components/schemas/FacetBucket'
description: Breakdown by filing year
note:
type: string
description: Explanatory note about facet limitations.
example: >-
Facet counts reflect keyword search results only; semantic (Pinecone)
results are not included in these counts.
FacetBucket:
type: object
description: A single bucket in a facet breakdown
properties:
key:
type: string
description: The value (e.g., "9th Cir.", "Federal Appellate", "2024")
count:
type: integer
description: Number of documents matching this value
SearchResultItem:
type: object
properties:
opinion_id:
type: string
description: Opinion identifier
score:
type: number
description: >-
Relevance score. Scale varies by mode: semantic 0-1 (cosine
similarity), keyword 0-100+ (BM25 score).
case_name:
type: string
description: Case name/caption
court_id:
type: string
description: Court identifier
court_name:
type: string
description: Full court name
court_abbreviation:
type: string
description: Court citation abbreviation
jurisdiction:
type: string
description: Jurisdiction type
state:
type: string
nullable: true
description: State name (null for federal courts)
publish_status:
type: string
nullable: true
description: Publication status, when available
enum:
- published
- unpublished
- unknown
- in_chambers
- separate
- errata
- relating_to
date_filed:
type: string
format: date
description: Filing date (YYYY-MM-DD)
docket_number:
type: string
nullable: true
description: Court docket number, when available
snippet:
type: string
description: Relevant text excerpt from the opinion
source:
type: string
enum:
- semantic
- keyword
description: >-
Source of this result. Always present in API responses: semantic mode
"semantic", keyword mode "keyword", hybrid mode varies per item.
PaginationMeta:
type: object
properties:
page:
type: integer
description: Current page number
page_size:
type: integer
description: Results per page
total_results:
type: integer
description: Total matching results (capped at 10,000 for keyword/hybrid)
total_pages:
type: integer
description: Total pages available
has_next:
type: boolean
description: Whether more pages exist
has_prev:
type: boolean
description: Whether previous pages exist
OpinionFull:
type: object
properties:
id:
type: string
description: Opinion identifier
case_name:
type: string
description: Case name/caption
court_id:
type: string
description: Court identifier
court_abbreviation:
type: string
description: Citation abbreviation
docket_number:
type: string
description: Court docket number
date_filed:
type: string
format: date
description: Filing date
state:
type: string
nullable: true
description: State name (null for federal courts)
publish_status:
type: string
enum:
- published
- unpublished
- unknown
- in_chambers
- separate
- errata
- relating_to
description: >-
Publication status for the opinion. Missing or uncertain metadata is
returned as unknown.
judge_name:
type: string
description: Authoring judge
citations:
type: array
items:
$ref: '#/components/schemas/Citation'
citation_count:
type: integer
description: Number of times this opinion is cited by other opinions
overall_treatment:
type: string
nullable: true
enum:
- Negative
- Caution
- Neutral
description: >-
Most negative treatment category from all citing opinions. Always
returned. Priority: Negative > Caution > Neutral > null (no treatment
data).
treatments:
type: array
items:
$ref: '#/components/schemas/Treatment'
description: >-
Citator treatments (only included if
include_detailed_treatments=true)
html_content:
type: string
description: Full opinion text in HTML (only included if include_content=true)
Citation:
type: object
properties:
cited_as:
type: string
description: Full citation string
volume:
type: string
description: Reporter volume
reporter:
type: string
description: Reporter abbreviation
page:
type: string
description: Starting page
Treatment:
type: object
properties:
citing_id:
type: string
description: ID of opinion citing this one
treatment_category:
type: string
description: Treatment type
treatment_description:
type: string
description: Detailed treatment
is_authoritative:
type: boolean
description: Whether authoritative
supporting_quote:
type: string
description: Quote supporting the treatment
CitationMatch:
type: object
description: Maps a requested citation to the opinion(s) it matched
properties:
citation:
type: string
description: The citation string from the request
example: 556 U.S. 662
opinion_id:
type: string
description: The matched opinion ID
example: '145875'
DocketLookup:
type: object
description: >-
Lookup by docket number and court. Requires docket_number and either
court_id or court_abbreviation.
required:
- docket_number
properties:
docket_number:
type: string
description: The docket number (e.g., "19-1392", "1:23-cv-01234")
example: 19-1392
court_id:
type: string
description: Court identifier (e.g., "scotus", "ca9", "nysd")
example: scotus
court_abbreviation:
type: string
description: Court citation abbreviation (e.g., "SCOTUS", "9th Cir.", "S.D.N.Y.")
example: SCOTUS
DocketMatch:
type: object
description: Maps a docket lookup to the opinion(s) it matched
properties:
docket_number:
type: string
description: The docket number that matched
example: 19-1392
court_id:
type: string
description: Court identifier
example: scotus
court_abbreviation:
type: string
description: Court citation abbreviation
example: SCOTUS
opinion_id:
type: string
description: The matched opinion ID
example: '145875'