Search
Choose source families, filters, result limits, and document retrieval.
POST /v1/search runs the same multi-stage legal retrieval and relevance pipeline used by Praven Intelekt. It returns sources and the most relevant provisions inside each source.
Request body
| Field | Type | Default | Notes |
|---|---|---|---|
query | string | required | 3–2,000 characters; Bulgarian produces the best results. |
source_types | string[] | automatic | Source families from the source-types catalog. |
court_ids | integer[] | none | Court IDs from the courts catalog. |
judge_name | string | none | Fuzzy, case-insensitive judge filter. |
date_from | YYYY-MM-DD | none | Inclusive lower publication date. |
date_to | YYYY-MM-DD | none | Inclusive upper publication date. |
max_results | integer | 20 | Between 1 and 50. |
include_content | boolean | false | Deprecated and ignored. Fetch full text with GET /v1/documents. |
Omit source_types when you want the API to select relevant families from the query. Pin source families for reproducible workflows or when domain knowledge makes the desired corpus explicit.
Discover filter values
List supported source families:
curl https://api.pravenintelekt.com/v1/catalog/source-types \
-H "X-API-Key: $PI_API_KEY"List court IDs:
curl https://api.pravenintelekt.com/v1/catalog/courts \
-H "X-API-Key: $PI_API_KEY"Find judges observed for a court:
curl --get https://api.pravenintelekt.com/v1/catalog/judges \
-H "X-API-Key: $PI_API_KEY" \
--data-urlencode "court=Софийски градски съд" \
--data-urlencode "search=Иванова" \
--data-urlencode "limit=25"court_ids only applies to court-case source families. Supplying court IDs with only non-court families returns invalid_request.
Results
Every result contains:
document_idandcollection: an opaque pair forGET /v1/documents.- Human-facing metadata such as
type,title,date,author, andurl. - Relevance data and a Bulgarian explanation when available.
- Court metadata such as decision number, case ID, and main judge when applicable.
excerpts: relevant articles or paragraphs with their own identifiers and scores.
Treat collection as opaque. Do not parse it or build business logic around an internal table name.
Latency and empty searches
Search typically takes 10–40 seconds. Set client timeouts above the expected maximum and avoid automatic retries after the server may have completed a billable request. A valid search with no matches returns HTTP 200 with result_count: 0 and an empty array.
Search results never include full document text. Retrieve only the documents a user opens with GET /v1/documents; this keeps payloads smaller and accounts for retrieval quota deliberately.