Search API

Hybrid semantic + keyword search across case law, legislation, and doctrine.

POST /v1/search

Search across legal documents with flexible filtering. Returns ranked results using a hybrid of vector similarity and BM25 keyword matching.

Request Body

Parameter	Type	Default	Description
`q`	string	required	Search query text
`namespace`	string	`case_law`	`case_law`, `legislation`, or `doctrine`
`top_k`	integer	`10`	Number of results (1–100)
`alpha`	float	`0.7`	Semantic weight (1.0 = pure semantic, 0.0 = pure keyword)
`result_detail`	string	`snippet`	Optional response detail level. Use `snippet` or omit for the backward-compatible default; use `full_text` only when you need bounded document text in search hits.
`country`	string[]	—	ISO country codes, e.g. `["FR","DE"]`
`source`	string[]	—	Source IDs, e.g. `["FR/Judilibre"]`
`court`	string	—	Court name filter
`court_tier`	integer	—	1 = supreme, 2 = appellate, 3 = first instance
`jurisdiction`	string	—	Jurisdiction name
`language`	string	—	Language code, e.g. `fr`
`date_start`	string	—	Start date (`YYYY-MM-DD`)
`date_end`	string	—	End date (`YYYY-MM-DD`)

MCP note: The MCP search tool also supports a subdivision parameter for filtering by administrative subdivision (e.g. state, province, Land).

Result Detail

result_detail controls how much content is included for each search hit. It is fully opt-in: omit it, or pass snippet, to keep the existing snippet-style response shape used by older clients.

Value	Behavior
`snippet` / omitted	Backward-compatible title, snippet, URL, and standard metadata fields.
`summary_only`	Concise summary/snippet-level content; case-law summaries are used when available.
`full_text`	Adds bounded `text`, `full_text_size`, and `text_truncated` when document text is available.
`full_metadata`	Adds full-text fields plus public legal metadata such as court, ECLI, authority, document type, article path, and dates.

Compatibility: Existing clients do not need to change anything. Full text and expanded metadata are returned only when requested with result_detail.

Requesting full text

curl -X POST https://legaldatahunter.com/v1/search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "right to be forgotten",
    "namespace": "case_law",
    "top_k": 3,
    "result_detail": "full_text"
  }'

Large text is bounded and marked with text_truncated and full_text_size. If text cannot be loaded for a hit, the hit is still returned with text_unavailable: true; the whole search does not fail.

Understanding Alpha

The alpha parameter controls the balance between semantic (vector) search and keyword (BM25) matching. Tune it based on your query type.

0.0

Pure keyword
Exact term matching

0.3

Keyword-heavy
Specific identifiers

0.7

Default (case law)
Balanced, semantic-leaning

0.9

Default (legislation)
Highly semantic

1.0

Pure semantic
Conceptual similarity

alpha=1.0 — Pure semantic. Finds conceptually similar results even with different wording. Best for broad legal concepts.
alpha=0.0 — Pure keyword. Exact term matching, ideal for specific case numbers or article identifiers.
alpha=0.7 (default for case_law) — Balanced, semantic-leaning. Good general-purpose setting.
alpha=0.9 (default for legislation) — More semantic, since legal text uses precise terminology that benefits from conceptual matching.

Tip: Lower alpha when searching for specific case numbers or article identifiers. Raise it when exploring a legal concept across jurisdictions.

Response Format

{
  "query": "right to be forgotten",
  "hits": [...],
  "total_hits": 5,
  "alpha": 0.7,
  "namespace": "case_law",
  "elapsed_ms": 342
}

Hit Fields

Field	Type	Description
`source`	string	Source identifier (e.g. `FR/Judilibre`)
`source_id`	string	Document ID within source
`score`	float	Relevance score (0–1)
`title`	string	Document title
`snippet`	string	Matching text excerpt (~300 chars)
`text`	string	Document text, returned only when `result_detail` is `full_text` or `full_metadata`
`full_text_size`	integer	Original text length when bounded full text is returned
`text_truncated`	boolean	Whether returned `text` was truncated to the configured maximum
`text_unavailable`	boolean	Present when full text was requested but could not be loaded for this hit
`summary`	string	Summary content, when available and requested by `summary_only` or `full_metadata`
`url`	string	Link to original source
`country`	string	ISO country code
`court`	string	Court name (case law only)
`court_tier`	integer	Court tier (1–3)
`date`	string	Decision or publication date
`jurisdiction`	string	Jurisdiction
`language`	string	Language code
`ecli`	string	ECLI identifier (if available)
`case_number`	string	Case number (if available)

Full Example

Request

curl -X POST https://legaldatahunter.com/v1/search \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "right to be forgotten",
    "namespace": "case_law",
    "top_k": 3,
    "country": ["FR"],
    "date_start": "2020-01-01"
  }'

Response

{
  "query": "right to be forgotten",
  "hits": [
    {
      "source": "FR/Judilibre",
      "source_id": "JURITEXT000046583921",
      "score": 0.94,
      "title": "Cour de cassation, 1re civ., 12 mai 2022",
      "snippet": "...le droit au déréférencement, expression du droit à l'oubli numérique, impose au moteur de recherche de supprimer les liens...",
      "url": "https://www.legifrance.gouv.fr/juri/id/JURITEXT000046583921",
      "country": "FR",
      "court": "Cour de cassation",
      "court_tier": 1,
      "date": "2022-05-12",
      "jurisdiction": "France",
      "language": "fr",
      "ecli": "ECLI:FR:CCASS:2022:C100438",
      "case_number": "21-12.532"
    },
    {
      "source": "FR/Judilibre",
      "source_id": "JURITEXT000044091287",
      "score": 0.87,
      "title": "Cour de cassation, 1re civ., 27 novembre 2021",
      "snippet": "...la mise en balance entre le droit à la vie privée et le droit à l'information du public...",
      "url": "https://www.legifrance.gouv.fr/juri/id/JURITEXT000044091287",
      "country": "FR",
      "court": "Cour de cassation",
      "court_tier": 1,
      "date": "2021-11-27",
      "jurisdiction": "France",
      "language": "fr",
      "ecli": "ECLI:FR:CCASS:2021:C100912",
      "case_number": "20-17.143"
    }
  ],
  "total_hits": 2,
  "alpha": 0.7,
  "namespace": "case_law",
  "elapsed_ms": 287
}

Filtering Examples

French case law from 2023 onward

{
  "q": "responsabilité civile du fait des algorithmes",
  "namespace": "case_law",
  "country": ["FR"],
  "date_start": "2023-01-01"
}

German supreme court decisions

{
  "q": "Datenschutz personenbezogene Daten",
  "namespace": "case_law",
  "country": ["DE"],
  "court_tier": 1
}

EU legislation about data protection

{
  "q": "personal data protection processing",
  "namespace": "legislation",
  "country": ["EU"],
  "alpha": 0.9
}

Next: Document Retrieval →