Prudai Developer API: conversations
Reading conversations, and deleting softly and restoring them.
Base URL https://api.prudai.com/v1. Logging in is in Login, scopes in Scopes and permissions, errors in Errors. Overview.
| Method | Path | What it does | State |
|---|---|---|---|
GET | /v1/conversations | List API conversations | In production |
POST | /v1/conversations | Start a conversation | In production |
GET | /v1/conversations/{conversation_id} | Get an API conversation | In production |
DELETE | /v1/conversations/{conversation_id} | Soft delete an API conversation | In production |
GET | /v1/conversations/{conversation_id}/messages | List API conversation messages | In production |
POST | /v1/conversations/{conversation_id}/messages | Send a message in a conversation | In production |
POST | /v1/conversations/{conversation_id}/restore | Restore a soft-deleted API conversation | In production |
List API conversations
GET /v1/conversations
Lists only conversations registered through this API in the calling organisation. Personal credentials see only their subject’s conversations; service credentials see all registered conversations of their organisation. App-only conversations are excluded. Deleted entries are hidden unless include_deleted is true and the credential also has an explicit conversations write or delete scope.
- State: in production.
- Scope:
prudai:conversations:read - Approval:
none, no extra step.
Parameters
product
One of:leo,leo-fiscaal,vera,bever,zia,maiamodel
max length 80include_deleted
default:falseq
Case-insensitive title substring. Wildcard characters are treated literally. max length 200limit
default:100· min 1 · max 200after
Opaque cursor from next_cursor. Bound to the authorised selection. max length 200
Responses
| Status | Meaning |
|---|---|
200 | One page, ordered by creation time descending with an id tie-breaker. |
400 | Malformed request or unsupported parameter (for example client-sent tools). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
Fields in data (200)
object
listdatadata[].id
pattern^conv_[A-Za-z0-9]{20}$data[].object
conversationdata[].product
One of:leo,leo-fiscaal,vera,bever,zia,maiadata[].model
max length 80data[].title
max length 500 · may benulldata[].created_atdata[].updated_atdata[].deleted_at
may benulldata[].purge_after
Restore deadline for a deleted entry, not a promise of content deletion. may benullhas_morenext_cursor
max length 200 · may benull
curl -s "https://api.prudai.com/v1/conversations" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo conversations list{ "object": "list", "data": [ { "id": "string", "object": "conversation", "product": "leo", "model": "string", "title": "string", "created_at": "2026-11-05T09:30:00.000Z", "updated_at": "2026-11-05T09:30:00.000Z", "deleted_at": "2026-11-05T09:30:00.000Z", "purge_after": "2026-11-05T09:30:00.000Z" } ], "has_more": false, "next_cursor": "string"}Start a conversation
POST /v1/conversations
Starts a new conversation with its first question: the same harness turn, product, depth, knowledge-base selection, tools and approvals as POST /chat/completions, addressed as a resource.
The body is the chat-completion request (model selects the product, prudai.knowledge_bases the organisation knowledge bases). prudai.conversation_id is refused here.
Completes with 201 and the completion, whose prudai.conversation_id is the new conversation (conv_…); continue it with POST /conversations/{conversation_id}/messages.
Pending actions return 202 with prudai.approvals, exactly as chat does. Streaming (stream: true) answers 200 text/event-stream.
Dossier (project) and per-conversation source selection are not accepted yet; the turn uses the product’s own sources.
- State: in production.
- Scope:
prudai:chat:read - Approval:
none, no extra step. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice.
Parameters
Idempotency-Key
Client-chosen unique key (we suggest a UUID) to make retries safe. Stored for 24 hours per credential and organisation (service key or personal token). Same key and same body: stored result is replayed and charged once. The knowledge-base operations (createKnowledgeBase,uploadKnowledgeBaseDocument) work differently: the key is bound to the organisation or knowledge base and lives as long as the object; see their descriptions. min length 8 · max length 255 · pattern^[\x21-\x7E]+$X-Client-Request-Id
Your own correlation id. Stored as request metadata and echoed in usage exports; not used for idempotency. max length 128 · pattern^[\x21-\x7E]+$
Body
JSON, required.
modelrequired
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max length 80 · pattern^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$messagesrequiredstream
default:falsestream_optionsstream_options.include_usage
Send a final chunk withusageand emptychoicesbefore[DONE]. default:falsereasoning_effort
low→ fast,medium→ standard,high→ thorough. Values above the model’s ceiling are clamped; the applied depth is reported inprudai.depth. Default: the model’sdefault_reasoning_effort. One of:low,medium,highstore
Onlytrue(the default) is supported. API conversations are stored as part of your organisation’s data;falsereturns400 unsupported_parameter.trueuser
Opaque id of your end user, for abuse detection and per-end-user usage filtering. Do not send names or e-mail addresses. max length 256temperature
Accepted and ignored. min 0 · max 2top_p
Accepted and ignored. min 0 · max 1presence_penalty
Accepted and ignored. min -2 · max 2frequency_penalty
Accepted and ignored. min -2 · max 2seed
Accepted and ignored.stop
Accepted and ignored.metadata
Accepted and ignored (max 16 string pairs).n
Only 1 is supported.1max_tokens
Accepted and ignored at launch (answer length is controlled by Prudai; a cut answer hasfinish_reasonlength). min 1max_completion_tokens
Accepted and ignored at launch, likemax_tokens. min 1logprobs
Onlyfalseis accepted;truereturns400 unsupported_parameter.falseresponse_format
Only{"type": "text"}is accepted; JSON modes return400 unsupported_parameter.response_format.typerequired
textprudai
Prudai extensions. With the OpenAI SDKs pass them viaextra_body={"prudai": {...}}.prudai.depth
Request Ultra depth. Overridesreasoning_effort. Requires the Ultra capability on your organisation (403 depth_not_permittedotherwise) and counts against the organisation’s Ultra daily quota (429 ultra_quota_exhaustedwhen used up). One of:ultraprudai.approvals
Pending actions. The exact approved arguments execute through the existing human approval flow.prudai.approvals[].idrequiredprudai.approvals[].levelrequired
One of:confirm,reviewprudai.approvals[].summaryrequiredprudai.approvals[].operationrequiredprudai.tool_events
Streamprudai.toolprogress chunks (only withstream: true). Those chunks have emptychoices. default:falseprudai.knowledge_bases
All accessible knowledge bases (default), none, or selected public ids. Requires the knowledge-bases read scope when selected explicitly. Without that scope the default becomes none with a notIncluded explanation. Environments without the knowledge-base adapter report the omission.prudai.conversation_id
pattern^conv_[A-Za-z0-9]{20}$prudai.citations
Whether citations are also returned as OpenAIurl_citationannotations. One of:annotations_and_prudai,prudai_only· default:"annotations_and_prudai"
Responses
| Status | Meaning |
|---|---|
200 | Streaming conversation start (text/event-stream); the final event carries the conversation id. |
201 | The conversation was started and the first answer completed. |
202 | The first answer waits for human approval of an action (prudai.approvals); the conversation exists and can be continued after the decision. The prudai.next member says what to do: read each request with getApproval, let a human decide in the Console, then send a new message on the same conversation_id. The approved call runs when that message arrives (the requester’s rights are checked again) and its outcome stands in the conversation as a tool result before the answer. |
400 | Malformed request or unsupported parameter (for example client-sent tools). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
402 | Not enough credits for this request, or a monthly spend cap has been reached. Only paid operations (phase 2) return it. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown model, source or document. |
409 | A request with the same Idempotency-Key is still running. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
502 | An upstream model provider or source failed. Not charged, except work that completed before the failure (reported in details.charged_credits). |
503 | Temporarily unavailable (maintenance, overload, or the credit check could not be performed). Nothing ran, nothing is charged. |
Fields in the response (200)
id
pattern^chatcmpl-[A-Za-z0-9]{24}$object
chat.completioncreatedmodel
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max length 80 · pattern^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$choiceschoices[].index
0choices[].messagechoices[].message.role
assistantchoices[].message.content
The answer in Markdown. Citation markers in the text correspond toprudai.citations[].marker. may benullchoices[].message.refusal
Set when the request was refused (thencontentis null andfinish_reasoniscontent_filter). may benullchoices[].message.annotations
OpenAI-compatible citations. Empty whenprudai.citationsisprudai_only.choices[].finish_reason
stopnormal end;lengththe answer was cut (output budget or the per-conversation cost breaker; seeprudai.stop_reason);content_filterthe answer was withheld by a safety boundary;approval_requiredmeans an action awaits human approval. One of:stop,length,content_filter,approval_requiredusage
Tokens summed over every model call Prudai made for this request, including tool rounds. Billing usesprudai.cost_credits, not a client-side token calculation.usage.prompt_tokens
min 0usage.completion_tokens
min 0usage.total_tokens
min 0usage.prompt_tokens_detailsusage.prompt_tokens_details.cached_tokens
min 0usage.completion_tokens_detailsusage.completion_tokens_details.reasoning_tokens
min 0prudaiprudai.conversation_id
pattern^conv_[A-Za-z0-9]{20}$prudai.citation_check
complete: every citation has a settledverified.pending: the citation audit had not finished when this answer was returned; read the stored result through listConversationMessages.unverifiable: the audit ran and at least one citation staysverified: null, for example a quote from a public source, which the audit cannot prove. One of:complete,pending,unverifiableprudai.context_truncated
Older supplied transcript content was omitted to respect the 60000-character limit.prudai.notIncludedprudai.notIncluded[].reason
What this result does not establish or include.prudai.notIncluded[].next
Ready call that can resolve this gap, or null if none is available. may benullprudai.tool_eventsprudai.tool_events[].event_id
Same id for thestartedand the matchingcompleted/failedevent.prudai.tool_events[].status
One of:started,completed,failedprudai.tool_events[].source_id
may benullprudai.tool_events[].labelprudai.tool_events[].result_count
min 0 · may benullprudai.request_id
pattern^req_[A-Za-z0-9]{24}$prudai.cost_credits
Credit charging is not activated for API chat. may benullprudai.price_list_version
Version of the published price list this metered request was priced with (see the credits and billing guide), also for free operations (priced at 0). A new version is published with its effective date whenever a model or provider price changes. Treat the value as an opaque identifier.prudai.depthprudai.depth.requested
Depth actually used.fast,standard,thoroughcorrespond toreasoning_effortlow,medium,high;ultrais only reachable throughprudai.depth. One of:fast,standard,thorough,ultraprudai.depth.applied
Depth actually used.fast,standard,thoroughcorrespond toreasoning_effortlow,medium,high;ultrais only reachable throughprudai.depth. One of:fast,standard,thorough,ultraprudai.depth.clamped
True whenappliedis lower thanrequestedbecause of the model’s or organisation’s depth ceiling.
This list stops after 40 fields.
Response format: text/event-stream.
curl -s -X POST "https://api.prudai.com/v1/conversations" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "model": "leo", "messages": [ { "role": "system", "content": "string", "name": "string" } ], "stream": false, "stream_options": { "include_usage": false }, "reasoning_effort": "low", "store": true, "user": "string", "temperature": 1, "top_p": 1, "presence_penalty": 1, "frequency_penalty": 1, "seed": 1, "stop": "string", "metadata": {}, "n": 1, "max_tokens": 1, "max_completion_tokens": 1, "logprobs": false, "response_format": { "type": "text" }, "prudai": { "depth": "ultra", "approvals": [ { "id": "string", "level": "confirm", "summary": "string", "operation": "string" } ], "tool_events": false, "knowledge_bases": "all", "conversation_id": "string", "citations": "annotations_and_prudai" } }'prudai leo conversations createGet an API conversation
GET /v1/conversations/{conversation_id}
Unknown, deleted, foreign-organisation and other users’ personal conversations return 404 document_not_found without disclosing their existence.
- State: in production.
- Scope:
prudai:conversations:read - Approval:
none, no extra step.
Parameters
conversation_idrequired
Opaque public API conversation id, never an internal app id. pattern^conv_[A-Za-z0-9]{20}$
Responses
| Status | Meaning |
|---|---|
200 | The registered conversation metadata. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown model, source or document. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
Fields in data (200)
id
pattern^conv_[A-Za-z0-9]{20}$object
conversationproduct
One of:leo,leo-fiscaal,vera,bever,zia,maiamodel
max length 80title
max length 500 · may benullcreated_atupdated_atdeleted_at
may benullpurge_after
Restore deadline for a deleted entry, not a promise of content deletion. may benull
curl -s "https://api.prudai.com/v1/conversations/<conversation_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo conversations get{ "id": "string", "object": "conversation", "product": "leo", "model": "string", "title": "string", "created_at": "2026-11-05T09:30:00.000Z", "updated_at": "2026-11-05T09:30:00.000Z", "deleted_at": "2026-11-05T09:30:00.000Z", "purge_after": "2026-11-05T09:30:00.000Z"}Soft delete an API conversation
DELETE /v1/conversations/{conversation_id}
Hides the API register entry from lists, gets and chat continuation. The underlying app conversation and messages remain subject to the existing retention policy. This does not call the app’s separate delete operation or remove any content. Returns 202 with an approval request until a human approves. dryRun=true previews unchanged metadata without modifying the register. Unknown or foreign conversations return 404 document_not_found before approval is requested.
- State: in production.
- Scope:
prudai:conversations:delete - Approval:
review, a second person or role approves. - Dry run:
?dryRun=trueshows what would happen and stores nothing. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice. - Deleting is soft; see Conventions.
Parameters
conversation_idrequired
Opaque public API conversation id, never an internal app id. pattern^conv_[A-Za-z0-9]{20}$dryRun
Validate and preview the operation without changing register entries. Approval is still required. default:falseIdempotency-Keyrequired
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern^[\x21-\x7E]+$x-prudai-approval
Approved one-use request id. Repeat the exact method, path, query and body. The grant is consumed before execution; obtain a new approval after a failed execution. Idempotency-Key is excluded from the approval fingerprint. pattern^apr_[A-Za-z0-9]{24}$
Responses
| Status | Meaning |
|---|---|
200 | Soft-deleted entry, or unchanged metadata for a dry run. |
202 | Human approval required. No action has run. Open approval_url, then repeat this call with x-prudai-approval. Pending requests last 15 minutes by default; approved grants last 10 minutes and can be used once. Personal tokens follow the same policy. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown model, source or document. |
409 | A request with the same Idempotency-Key is still running. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
Fields in data (200)
id
pattern^conv_[A-Za-z0-9]{20}$object
conversationproduct
One of:leo,leo-fiscaal,vera,bever,zia,maiamodel
max length 80title
max length 500 · may benullcreated_atupdated_atdeleted_at
may benullpurge_after
Restore deadline for a deleted entry, not a promise of content deletion. may benull
curl -s -X DELETE "https://api.prudai.com/v1/conversations/<conversation_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"prudai leo conversations delete{ "id": "string", "object": "conversation", "product": "leo", "model": "string", "title": "string", "created_at": "2026-11-05T09:30:00.000Z", "updated_at": "2026-11-05T09:30:00.000Z", "deleted_at": "2026-11-05T09:30:00.000Z", "purge_after": "2026-11-05T09:30:00.000Z"}List API conversation messages
GET /v1/conversations/{conversation_id}/messages
Returns user and assistant text in chronological order, retaining citation markers. Tool and system rows and all internal message and conversation ids are excluded. verified, identifier_exists and quote_verified come from the stored citation audit, with the same meaning as in a completion; citations is empty until that audit has run. Each text is limited to 200000 characters and carries truncated. A page has at most 200 messages; the complete response is bounded to 1 MiB, so a page may contain fewer messages. The text budget per message depends on the requested page limit; requesting a smaller page allows longer text. Omitted audit data or citation projection also sets truncated. The next call advances past the last returned message and always terminates.
- State: in production.
- Scope:
prudai:conversations:read - Approval:
none, no extra step.
Parameters
conversation_idrequired
Opaque public API conversation id, never an internal app id. pattern^conv_[A-Za-z0-9]{20}$limit
Messages per page (default 10). A message is returned in full up to 200 000 characters for pages of up to 19 messages; larger pages shorten each message proportionally and settruncated. default:10· min 1 · max 200after
Opaque cursor from next_cursor. Bound to the authorised selection. max length 200
Responses
| Status | Meaning |
|---|---|
200 | One bounded page of messages. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown model, source or document. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
Fields in data (200)
object
listdatadata[].role
One of:user,assistantdata[].text
Message text with its original citation markers. max length 200000data[].citationsdata[].citations[].reference
Public source reference from the stored audit.data[].citations[].verified
Same meaning as PrudaiCitation.verified. A stored audit is per reference: when one mention of a reference carries a quote, the reference reads as quoted (verified: nulluntil disproved), also if the completion marked another, unquoted mention of itverified: true. Two quoted mentions can give two entries with the same reference. Text that could not be read in full counts as quoted, so a truncated message can readnullwhere the completion saidtrue; a disproved citation staysfalse. may benulldata[].citations[].identifier_exists
Same meaning as PrudaiCitation.identifier_exists. may benulldata[].citations[].quote_verified
Same meaning as PrudaiCitation.quote_verified. may benulldata[].created_atdata[].truncated
True when the text or citation projection was limited by the output budget.has_morenext_cursor
max length 200 · may benull
curl -s "https://api.prudai.com/v1/conversations/<conversation_id>/messages" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo conversations-messages list{ "object": "list", "data": [ { "role": "user", "text": "string", "citations": [ { "reference": "string", "verified": false, "identifier_exists": false, "quote_verified": false } ], "created_at": "2026-11-05T09:30:00.000Z", "truncated": false } ], "has_more": false, "next_cursor": "string"}Send a message in a conversation
POST /v1/conversations/{conversation_id}/messages
Continues an existing API conversation: an alias of POST /chat/completions with prudai.conversation_id taken from the path (a body that names another conversation is refused with 422). The response is the chat completion; pending actions return 202 with prudai.approvals, and an approved action has already run and its outcome stands in the conversation by the next message.
- State: in production.
- Scope:
prudai:chat:read - Approval:
none, no extra step. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice.
Parameters
conversation_idrequired
pattern^conv_[A-Za-z0-9]{20}$Idempotency-Key
Client-chosen unique key (we suggest a UUID) to make retries safe. Stored for 24 hours per credential and organisation (service key or personal token). Same key and same body: stored result is replayed and charged once. The knowledge-base operations (createKnowledgeBase,uploadKnowledgeBaseDocument) work differently: the key is bound to the organisation or knowledge base and lives as long as the object; see their descriptions. min length 8 · max length 255 · pattern^[\x21-\x7E]+$X-Client-Request-Id
Your own correlation id. Stored as request metadata and echoed in usage exports; not used for idempotency. max length 128 · pattern^[\x21-\x7E]+$
Body
JSON, required.
modelrequired
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max length 80 · pattern^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$messagesrequiredstream
default:falsestream_optionsstream_options.include_usage
Send a final chunk withusageand emptychoicesbefore[DONE]. default:falsereasoning_effort
low→ fast,medium→ standard,high→ thorough. Values above the model’s ceiling are clamped; the applied depth is reported inprudai.depth. Default: the model’sdefault_reasoning_effort. One of:low,medium,highstore
Onlytrue(the default) is supported. API conversations are stored as part of your organisation’s data;falsereturns400 unsupported_parameter.trueuser
Opaque id of your end user, for abuse detection and per-end-user usage filtering. Do not send names or e-mail addresses. max length 256temperature
Accepted and ignored. min 0 · max 2top_p
Accepted and ignored. min 0 · max 1presence_penalty
Accepted and ignored. min -2 · max 2frequency_penalty
Accepted and ignored. min -2 · max 2seed
Accepted and ignored.stop
Accepted and ignored.metadata
Accepted and ignored (max 16 string pairs).n
Only 1 is supported.1max_tokens
Accepted and ignored at launch (answer length is controlled by Prudai; a cut answer hasfinish_reasonlength). min 1max_completion_tokens
Accepted and ignored at launch, likemax_tokens. min 1logprobs
Onlyfalseis accepted;truereturns400 unsupported_parameter.falseresponse_format
Only{"type": "text"}is accepted; JSON modes return400 unsupported_parameter.response_format.typerequired
textprudai
Prudai extensions. With the OpenAI SDKs pass them viaextra_body={"prudai": {...}}.prudai.depth
Request Ultra depth. Overridesreasoning_effort. Requires the Ultra capability on your organisation (403 depth_not_permittedotherwise) and counts against the organisation’s Ultra daily quota (429 ultra_quota_exhaustedwhen used up). One of:ultraprudai.approvals
Pending actions. The exact approved arguments execute through the existing human approval flow.prudai.approvals[].idrequiredprudai.approvals[].levelrequired
One of:confirm,reviewprudai.approvals[].summaryrequiredprudai.approvals[].operationrequiredprudai.tool_events
Streamprudai.toolprogress chunks (only withstream: true). Those chunks have emptychoices. default:falseprudai.knowledge_bases
All accessible knowledge bases (default), none, or selected public ids. Requires the knowledge-bases read scope when selected explicitly. Without that scope the default becomes none with a notIncluded explanation. Environments without the knowledge-base adapter report the omission.prudai.conversation_id
pattern^conv_[A-Za-z0-9]{20}$prudai.citations
Whether citations are also returned as OpenAIurl_citationannotations. One of:annotations_and_prudai,prudai_only· default:"annotations_and_prudai"
Responses
| Status | Meaning |
|---|---|
200 | The completion (application/json) or, with stream: true, text/event-stream. |
202 | The answer waits for human approval of an action (prudai.approvals). The prudai.next member says what to do: read each request with getApproval, let a human decide in the Console, then send a new message on the same conversation_id. The approved call runs when that message arrives (the requester’s rights are checked again) and its outcome stands in the conversation as a tool result before the answer. |
400 | Malformed request or unsupported parameter (for example client-sent tools). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
402 | Not enough credits for this request, or a monthly spend cap has been reached. Only paid operations (phase 2) return it. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown model, source or document. |
409 | A request with the same Idempotency-Key is still running. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
502 | An upstream model provider or source failed. Not charged, except work that completed before the failure (reported in details.charged_credits). |
503 | Temporarily unavailable (maintenance, overload, or the credit check could not be performed). Nothing ran, nothing is charged. |
Fields in the response (200)
id
pattern^chatcmpl-[A-Za-z0-9]{24}$object
chat.completioncreatedmodel
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max length 80 · pattern^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$choiceschoices[].index
0choices[].messagechoices[].message.role
assistantchoices[].message.content
The answer in Markdown. Citation markers in the text correspond toprudai.citations[].marker. may benullchoices[].message.refusal
Set when the request was refused (thencontentis null andfinish_reasoniscontent_filter). may benullchoices[].message.annotations
OpenAI-compatible citations. Empty whenprudai.citationsisprudai_only.choices[].finish_reason
stopnormal end;lengththe answer was cut (output budget or the per-conversation cost breaker; seeprudai.stop_reason);content_filterthe answer was withheld by a safety boundary;approval_requiredmeans an action awaits human approval. One of:stop,length,content_filter,approval_requiredusage
Tokens summed over every model call Prudai made for this request, including tool rounds. Billing usesprudai.cost_credits, not a client-side token calculation.usage.prompt_tokens
min 0usage.completion_tokens
min 0usage.total_tokens
min 0usage.prompt_tokens_detailsusage.prompt_tokens_details.cached_tokens
min 0usage.completion_tokens_detailsusage.completion_tokens_details.reasoning_tokens
min 0prudaiprudai.conversation_id
pattern^conv_[A-Za-z0-9]{20}$prudai.citation_check
complete: every citation has a settledverified.pending: the citation audit had not finished when this answer was returned; read the stored result through listConversationMessages.unverifiable: the audit ran and at least one citation staysverified: null, for example a quote from a public source, which the audit cannot prove. One of:complete,pending,unverifiableprudai.context_truncated
Older supplied transcript content was omitted to respect the 60000-character limit.prudai.notIncludedprudai.notIncluded[].reason
What this result does not establish or include.prudai.notIncluded[].next
Ready call that can resolve this gap, or null if none is available. may benullprudai.tool_eventsprudai.tool_events[].event_id
Same id for thestartedand the matchingcompleted/failedevent.prudai.tool_events[].status
One of:started,completed,failedprudai.tool_events[].source_id
may benullprudai.tool_events[].labelprudai.tool_events[].result_count
min 0 · may benullprudai.request_id
pattern^req_[A-Za-z0-9]{24}$prudai.cost_credits
Credit charging is not activated for API chat. may benullprudai.price_list_version
Version of the published price list this metered request was priced with (see the credits and billing guide), also for free operations (priced at 0). A new version is published with its effective date whenever a model or provider price changes. Treat the value as an opaque identifier.prudai.depthprudai.depth.requested
Depth actually used.fast,standard,thoroughcorrespond toreasoning_effortlow,medium,high;ultrais only reachable throughprudai.depth. One of:fast,standard,thorough,ultraprudai.depth.applied
Depth actually used.fast,standard,thoroughcorrespond toreasoning_effortlow,medium,high;ultrais only reachable throughprudai.depth. One of:fast,standard,thorough,ultraprudai.depth.clamped
True whenappliedis lower thanrequestedbecause of the model’s or organisation’s depth ceiling.
This list stops after 40 fields.
Response format: text/event-stream.
curl -s -X POST "https://api.prudai.com/v1/conversations/<conversation_id>/messages" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "model": "leo", "messages": [ { "role": "system", "content": "string", "name": "string" } ], "stream": false, "stream_options": { "include_usage": false }, "reasoning_effort": "low", "store": true, "user": "string", "temperature": 1, "top_p": 1, "presence_penalty": 1, "frequency_penalty": 1, "seed": 1, "stop": "string", "metadata": {}, "n": 1, "max_tokens": 1, "max_completion_tokens": 1, "logprobs": false, "response_format": { "type": "text" }, "prudai": { "depth": "ultra", "approvals": [ { "id": "string", "level": "confirm", "summary": "string", "operation": "string" } ], "tool_events": false, "knowledge_bases": "all", "conversation_id": "string", "citations": "annotations_and_prudai" } }'prudai leo conversations-messages createRestore a soft-deleted API conversation
POST /v1/conversations/{conversation_id}/restore
Restores the register entry only before purge_after. An expired restore returns 410 document_not_found; foreign or unknown entries return 404 document_not_found. Restoring an active entry is safe and returns its current metadata. Returns 202 with an approval request until a human approves. dryRun=true previews unchanged metadata without modifying the register. Idempotency is stored for 24 hours per organisation and operation, including the conversation and dry-run choice in the request fingerprint. A replay returns the stored result; a concurrent request returns 409 idempotency_request_in_progress; a changed request with the same key returns 422 idempotency_key_reused.
- State: in production.
- Scope:
prudai:conversations:write - Approval:
confirm, the user confirms exactly this call. - Dry run:
?dryRun=trueshows what would happen and stores nothing. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice.
Parameters
conversation_idrequired
Opaque public API conversation id, never an internal app id. pattern^conv_[A-Za-z0-9]{20}$dryRun
Validate and preview the operation without changing register entries. Approval is still required. default:falseIdempotency-Keyrequired
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern^[\x21-\x7E]+$x-prudai-approval
Approved one-use request id. Repeat the exact method, path, query and body. The grant is consumed before execution; obtain a new approval after a failed execution. Idempotency-Key is excluded from the approval fingerprint. pattern^apr_[A-Za-z0-9]{24}$
Responses
| Status | Meaning |
|---|---|
200 | Restored entry, or unchanged metadata for a dry run. |
202 | Human approval required. No action has run. Open approval_url, then repeat this call with x-prudai-approval. Pending requests last 15 minutes by default; approved grants last 10 minutes and can be used once. Personal tokens follow the same policy. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown model, source or document. |
409 | A request with the same Idempotency-Key is still running. |
410 | The restore window expired. Uses document_not_found in the standard error envelope. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
500 | Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits). |
Fields in data (200)
id
pattern^conv_[A-Za-z0-9]{20}$object
conversationproduct
One of:leo,leo-fiscaal,vera,bever,zia,maiamodel
max length 80title
max length 500 · may benullcreated_atupdated_atdeleted_at
may benullpurge_after
Restore deadline for a deleted entry, not a promise of content deletion. may benull
curl -s -X POST "https://api.prudai.com/v1/conversations/<conversation_id>/restore" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"prudai leo conversations restore{ "id": "string", "object": "conversation", "product": "leo", "model": "string", "title": "string", "created_at": "2026-11-05T09:30:00.000Z", "updated_at": "2026-11-05T09:30:00.000Z", "deleted_at": "2026-11-05T09:30:00.000Z", "purge_after": "2026-11-05T09:30:00.000Z"}