Prudai Developer API: chat
Een chatantwoord van een model, met of zonder streaming, in de vorm van de OpenAI Chat Completions-API.
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 |
|---|---|---|---|
POST | /v1/chat/completions | Chatantwoord maken | Op productie |
Chatantwoord maken
POST /v1/chat/completions
Create a chat completion.
OpenAI-compatible chat completion. Prudai runs its research harness server-side (sources, citation checks, depth ladder) and returns the answer with citations.
Streaming. With "stream": true the response is text/event-stream. Each event is
one line data: <json> followed by a blank line. The JSON is a
ChatCompletionChunk (or, mid-stream, a StreamErrorEvent). The stream always ends
with the literal line data: [DONE]. Keep-alive comments (: keep-alive) may be sent
while the harness is researching; SSE clients ignore them.
Not supported (400). tools, tool_choice, functions, function_call,
parallel_tool_calls (code tools_not_supported); n other than 1, logprobs: true,
top_logprobs, response_format other than {"type":"text"}, audio, modalities,
prediction, store: false, image or file content parts, and messages with role
tool/function (code unsupported_parameter). Any other unknown top-level request
property is also a 400, so mistakes are not silently ignored.
Accepted and ignored. temperature, top_p, presence_penalty,
frequency_penalty, seed, stop, metadata, max_tokens,
max_completion_tokens, logprobs: false, response_format: {"type":"text"}.
The harness controls sampling and answer length.
Idempotency. Send Idempotency-Key to retry safely. Within 24 hours the same key
with the same body returns the stored result (header Idempotent-Replayed: true) and
is charged once; while the first request is still running a retry gets
409 idempotency_request_in_progress; the same key with a different body gets
422 idempotency_key_reused. A request that fails before its conversation was created
(for example a 429 or 502 from the upstream) releases the key, so the retry runs. A request
that fails after its conversation was created keeps the key reserved until it expires after
24 hours, so a retry never starts a second harness turn. Streaming requests cannot be
replayed after completion; reuse of their key returns 409.
Chat requires a user Keycloak access token obtained through product token exchange.
Service keys and personal API tokens return 403 chat_requires_user_token.
Requests time out after 240 seconds and answers are bounded to 1 MiB.
Writing follows the signed-in person: a user token whose account role is a writing role
in the signed-in account (owner, admin, member or sales) carries prudai:chat:write; a
viewer does not. No request field or header grants it, and it is never issued to service
keys or personal API tokens (those cannot chat at all). Without it the harness retains its
read-only tool policy. With it, internal reversible actions run directly; actions needing
approval in the app create a pending approval request.
Pending actions return HTTP 202 for non-streaming JSON, including idempotency replay;
streaming keeps HTTP 200 and reports the pending actions in its final result.
Read-only and completed direct-action responses retain HTTP 200.
Both JSON responses and the final SSE result report prudai.approvals and
finish_reason / stop_reason: approval_required. Approve through the existing human
console flow, then continue with a new message on the same conversation_id.
- 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 | The completion. application/json when stream is false or absent, text/event-stream when stream is true. |
202 | Non-streaming completion with actions awaiting human approval. The response includes prudai.approvals and finish_reason / prudai.stop_reason: approval_required. Replaying its Idempotency-Key preserves HTTP 202. Streaming uses HTTP 200 and the final SSE result carries the same pending-action details. 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. |
504 | The request exceeded the maximum duration. Only work that completed is charged (reported in details.charged_credits). |
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/chat/completions" \ -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 chat completions