Answers
Create and poll asynchronous, citation-grounded answer jobs.
The Answers API combines legal search with a Bulgarian answer grounded in the returned sources. It is asynchronous because end-to-end work commonly takes 30–90 seconds.
Create a job
POST /v1/answers accepts the same search filters as POST /v1/search. include_content is ignored.
curl --request POST \
--url https://api.pravenintelekt.com/v1/answers \
--header "Content-Type: application/json" \
--header "X-API-Key: $PI_API_KEY" \
--data '{
"query": "Може ли работодателят да прекрати трудов договор по време на отпуск?",
"max_results": 10
}'The API returns HTTP 202 immediately:
{
"job_id": "…",
"status": "queued",
"poll_url": "/v1/answers/…"
}Poll for completion
Send the same API key to the relative poll_url. Poll after 2 seconds, then use capped exponential backoff up to 10 seconds. Stop after a terminal state.
curl https://api.pravenintelekt.com/v1/answers/JOB_ID \
-H "X-API-Key: $PI_API_KEY"Possible statuses are queued, running, succeeded, and failed.
{
"job_id": "…",
"status": "succeeded",
"query": "…",
"answer": "… [citation] …",
"sources": []
}Bracketed citation markers in answer refer to excerpt_id or document_id values in sources. Preserve those relationships if your application transforms the response.
Failure behavior
Failed jobs return HTTP 200 with status: "failed", error_code, and error_message. They do not consume an answer unit. A job that remains queued or running for 15 minutes is marked timed_out when read and refunded.
The beta implementation runs jobs in the accepting API worker. A worker restart can orphan in-flight work; the timeout path detects and refunds it. Durable queues and completion webhooks are not available yet, so consumers must poll and tolerate a refunded retry after a terminal failure.
When to use search instead
Use /v1/search when your product presents sources, implements its own review workflow, or synthesizes an answer with a separate model. Use /v1/answers when you need Praven Intelekt's grounded answer and citation-repair pipeline.