Prudai Developer API: gesprekken
Gesprekken lezen, en zacht verwijderen en herstellen.
Basis-URL https://api.prudai.com/v1. Inloggen staat in Inloggen, scopes in Scopes en rechten, fouten in Fouten. Overzicht.
| Methode | Pad | Wat het doet | Stand |
|---|---|---|---|
GET | /v1/conversations | Gesprekken opvragen | Op productie |
POST | /v1/conversations | Start a conversation | Op productie |
GET | /v1/conversations/{conversation_id} | Eén gesprek opvragen | Op productie |
DELETE | /v1/conversations/{conversation_id} | Gesprek verwijderen | Op productie |
GET | /v1/conversations/{conversation_id}/messages | Berichten van een gesprek opvragen | Op productie |
POST | /v1/conversations/{conversation_id}/messages | Send a message in a conversation | Op productie |
POST | /v1/conversations/{conversation_id}/restore | Gesprek herstellen | Op productie |
Gesprekken opvragen
GET /v1/conversations
List API 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.
- Stand: op productie.
- Scope:
prudai:conversations:read - Goedkeuring:
none, geen extra stap.
Parameters
product
Een van:leo,leo-fiscaal,vera,bever,zia,maiamodel
max. lengte 80include_deleted
standaard:falseq
Case-insensitive title substring. Wildcard characters are treated literally. max. lengte 200limit
standaard:100· min. 1 · max. 200after
Opaque cursor from next_cursor. Bound to the authorised selection. max. lengte 200
Antwoorden
| Status | Betekenis |
|---|---|
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). |
Velden in data (200)
object
listdatadata[].id
patroon^conv_[A-Za-z0-9]{20}$data[].object
conversationdata[].product
Een van:leo,leo-fiscaal,vera,bever,zia,maiadata[].model
max. lengte 80data[].title
max. lengte 500 · kannullzijndata[].created_atdata[].updated_atdata[].deleted_at
kannullzijndata[].purge_after
Restore deadline for a deleted entry, not a promise of content deletion. kannullzijnhas_morenext_cursor
max. lengte 200 · kannullzijn
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.
- Stand: op productie.
- Scope:
prudai:chat:read - Goedkeuring:
none, geen extra stap. - Idempotentie: stuur
Idempotency-Keymee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.
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. lengte 8 · max. lengte 255 · patroon^[\x21-\x7E]+$X-Client-Request-Id
Your own correlation id. Stored as request metadata and echoed in usage exports; not used for idempotency. max. lengte 128 · patroon^[\x21-\x7E]+$
Body
JSON, verplicht.
modelverplicht
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max. lengte 80 · patroon^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$messagesverplichtstream
standaard:falsestream_optionsstream_options.include_usage
Send a final chunk withusageand emptychoicesbefore[DONE]. standaard: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. Een van: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. lengte 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.typeverplicht
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). Een van:ultraprudai.approvals
Pending actions. The exact approved arguments execute through the existing human approval flow.prudai.approvals[].idverplichtprudai.approvals[].levelverplicht
Een van:confirm,reviewprudai.approvals[].summaryverplichtprudai.approvals[].operationverplichtprudai.tool_events
Streamprudai.toolprogress chunks (only withstream: true). Those chunks have emptychoices. standaard: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
patroon^conv_[A-Za-z0-9]{20}$prudai.citations
Whether citations are also returned as OpenAIurl_citationannotations. Een van:annotations_and_prudai,prudai_only· standaard:"annotations_and_prudai"
Antwoorden
| Status | Betekenis |
|---|---|
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. |
Velden in het antwoord (200)
id
patroon^chatcmpl-[A-Za-z0-9]{24}$object
chat.completioncreatedmodel
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max. lengte 80 · patroon^(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. kannullzijnchoices[].message.refusal
Set when the request was refused (thencontentis null andfinish_reasoniscontent_filter). kannullzijnchoices[].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. Een van: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
patroon^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. Een van: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. kannullzijnprudai.tool_eventsprudai.tool_events[].event_id
Same id for thestartedand the matchingcompleted/failedevent.prudai.tool_events[].status
Een van:started,completed,failedprudai.tool_events[].source_id
kannullzijnprudai.tool_events[].labelprudai.tool_events[].result_count
min. 0 · kannullzijnprudai.request_id
patroon^req_[A-Za-z0-9]{24}$prudai.cost_credits
Credit charging is not activated for API chat. kannullzijnprudai.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. Een van:fast,standard,thorough,ultraprudai.depth.applied
Depth actually used.fast,standard,thoroughcorrespond toreasoning_effortlow,medium,high;ultrais only reachable throughprudai.depth. Een van:fast,standard,thorough,ultraprudai.depth.clamped
True whenappliedis lower thanrequestedbecause of the model’s or organisation’s depth ceiling.
Deze lijst stopt na 40 velden.
Formaat van het antwoord: 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 createEén gesprek opvragen
GET /v1/conversations/{conversation_id}
Get an API conversation.
Unknown, deleted, foreign-organisation and other users’ personal conversations return 404 document_not_found without disclosing their existence.
- Stand: op productie.
- Scope:
prudai:conversations:read - Goedkeuring:
none, geen extra stap.
Parameters
conversation_idverplicht
Opaque public API conversation id, never an internal app id. patroon^conv_[A-Za-z0-9]{20}$
Antwoorden
| Status | Betekenis |
|---|---|
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). |
Velden in data (200)
id
patroon^conv_[A-Za-z0-9]{20}$object
conversationproduct
Een van:leo,leo-fiscaal,vera,bever,zia,maiamodel
max. lengte 80title
max. lengte 500 · kannullzijncreated_atupdated_atdeleted_at
kannullzijnpurge_after
Restore deadline for a deleted entry, not a promise of content deletion. kannullzijn
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"}Gesprek verwijderen
DELETE /v1/conversations/{conversation_id}
Soft delete an API conversation.
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.
- Stand: op productie.
- Scope:
prudai:conversations:delete - Goedkeuring:
review, een tweede persoon of rol keurt goed. - Dry run:
?dryRun=truelaat zien wat er zou gebeuren en slaat niets op. - Idempotentie: stuur
Idempotency-Keymee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit. - Verwijderen is zacht; zie Conventies.
Parameters
conversation_idverplicht
Opaque public API conversation id, never an internal app id. patroon^conv_[A-Za-z0-9]{20}$dryRun
Validate and preview the operation without changing register entries. Approval is still required. standaard:falseIdempotency-Keyverplicht
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min. lengte 8 · max. lengte 255 · patroon^[\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. patroon^apr_[A-Za-z0-9]{24}$
Antwoorden
| Status | Betekenis |
|---|---|
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). |
Velden in data (200)
id
patroon^conv_[A-Za-z0-9]{20}$object
conversationproduct
Een van:leo,leo-fiscaal,vera,bever,zia,maiamodel
max. lengte 80title
max. lengte 500 · kannullzijncreated_atupdated_atdeleted_at
kannullzijnpurge_after
Restore deadline for a deleted entry, not a promise of content deletion. kannullzijn
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"}Berichten van een gesprek opvragen
GET /v1/conversations/{conversation_id}/messages
List API conversation 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.
- Stand: op productie.
- Scope:
prudai:conversations:read - Goedkeuring:
none, geen extra stap.
Parameters
conversation_idverplicht
Opaque public API conversation id, never an internal app id. patroon^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. standaard:10· min. 1 · max. 200after
Opaque cursor from next_cursor. Bound to the authorised selection. max. lengte 200
Antwoorden
| Status | Betekenis |
|---|---|
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). |
Velden in data (200)
object
listdatadata[].role
Een van:user,assistantdata[].text
Message text with its original citation markers. max. lengte 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. kannullzijndata[].citations[].identifier_exists
Same meaning as PrudaiCitation.identifier_exists. kannullzijndata[].citations[].quote_verified
Same meaning as PrudaiCitation.quote_verified. kannullzijndata[].created_atdata[].truncated
True when the text or citation projection was limited by the output budget.has_morenext_cursor
max. lengte 200 · kannullzijn
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.
- Stand: op productie.
- Scope:
prudai:chat:read - Goedkeuring:
none, geen extra stap. - Idempotentie: stuur
Idempotency-Keymee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.
Parameters
conversation_idverplicht
patroon^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. lengte 8 · max. lengte 255 · patroon^[\x21-\x7E]+$X-Client-Request-Id
Your own correlation id. Stored as request metadata and echoed in usage exports; not used for idempotency. max. lengte 128 · patroon^[\x21-\x7E]+$
Body
JSON, verplicht.
modelverplicht
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max. lengte 80 · patroon^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$messagesverplichtstream
standaard:falsestream_optionsstream_options.include_usage
Send a final chunk withusageand emptychoicesbefore[DONE]. standaard: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. Een van: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. lengte 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.typeverplicht
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). Een van:ultraprudai.approvals
Pending actions. The exact approved arguments execute through the existing human approval flow.prudai.approvals[].idverplichtprudai.approvals[].levelverplicht
Een van:confirm,reviewprudai.approvals[].summaryverplichtprudai.approvals[].operationverplichtprudai.tool_events
Streamprudai.toolprogress chunks (only withstream: true). Those chunks have emptychoices. standaard: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
patroon^conv_[A-Za-z0-9]{20}$prudai.citations
Whether citations are also returned as OpenAIurl_citationannotations. Een van:annotations_and_prudai,prudai_only· standaard:"annotations_and_prudai"
Antwoorden
| Status | Betekenis |
|---|---|
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. |
Velden in het antwoord (200)
id
patroon^chatcmpl-[A-Za-z0-9]{24}$object
chat.completioncreatedmodel
A product, optionally followed by/and a specialisation slug (e.g.leo/arbeidsrecht). max. lengte 80 · patroon^(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. kannullzijnchoices[].message.refusal
Set when the request was refused (thencontentis null andfinish_reasoniscontent_filter). kannullzijnchoices[].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. Een van: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
patroon^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. Een van: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. kannullzijnprudai.tool_eventsprudai.tool_events[].event_id
Same id for thestartedand the matchingcompleted/failedevent.prudai.tool_events[].status
Een van:started,completed,failedprudai.tool_events[].source_id
kannullzijnprudai.tool_events[].labelprudai.tool_events[].result_count
min. 0 · kannullzijnprudai.request_id
patroon^req_[A-Za-z0-9]{24}$prudai.cost_credits
Credit charging is not activated for API chat. kannullzijnprudai.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. Een van:fast,standard,thorough,ultraprudai.depth.applied
Depth actually used.fast,standard,thoroughcorrespond toreasoning_effortlow,medium,high;ultrais only reachable throughprudai.depth. Een van:fast,standard,thorough,ultraprudai.depth.clamped
True whenappliedis lower thanrequestedbecause of the model’s or organisation’s depth ceiling.
Deze lijst stopt na 40 velden.
Formaat van het antwoord: 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 createGesprek herstellen
POST /v1/conversations/{conversation_id}/restore
Restore a soft-deleted API conversation.
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.
- Stand: op productie.
- Scope:
prudai:conversations:write - Goedkeuring:
confirm, de gebruiker bevestigt precies deze aanroep. - Dry run:
?dryRun=truelaat zien wat er zou gebeuren en slaat niets op. - Idempotentie: stuur
Idempotency-Keymee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.
Parameters
conversation_idverplicht
Opaque public API conversation id, never an internal app id. patroon^conv_[A-Za-z0-9]{20}$dryRun
Validate and preview the operation without changing register entries. Approval is still required. standaard:falseIdempotency-Keyverplicht
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min. lengte 8 · max. lengte 255 · patroon^[\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. patroon^apr_[A-Za-z0-9]{24}$
Antwoorden
| Status | Betekenis |
|---|---|
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). |
Velden in data (200)
id
patroon^conv_[A-Za-z0-9]{20}$object
conversationproduct
Een van:leo,leo-fiscaal,vera,bever,zia,maiamodel
max. lengte 80title
max. lengte 500 · kannullzijncreated_atupdated_atdeleted_at
kannullzijnpurge_after
Restore deadline for a deleted entry, not a promise of content deletion. kannullzijn
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"}