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)
`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).

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)
`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 →