Ga naar inhoud

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.

MethodePadWat het doetStand
POST/v1/chat/completionsChatantwoord makenOp 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-Key mee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.

Parameters

  • Idempotency-Key header · string
    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 header · string
    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.

  • model string verplicht
    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]+)*)?$
  • messages array<object> verplicht
  • stream boolean
    standaard: false
  • stream_options StreamOptions
  • stream_options.include_usage boolean
    Send a final chunk with usage and empty choices before [DONE]. standaard: false
  • reasoning_effort string
    low → fast, medium → standard, high → thorough. Values above the model’s ceiling are clamped; the applied depth is reported in prudai.depth. Default: the model’s default_reasoning_effort. Een van: low, medium, high
  • store boolean
    Only true (the default) is supported. API conversations are stored as part of your organisation’s data; false returns 400 unsupported_parameter. true
  • user string
    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 256
  • temperature number
    Accepted and ignored. min. 0 · max. 2
  • top_p number
    Accepted and ignored. min. 0 · max. 1
  • presence_penalty number
    Accepted and ignored. min. -2 · max. 2
  • frequency_penalty number
    Accepted and ignored. min. -2 · max. 2
  • seed integer
    Accepted and ignored.
  • stop string or array<string>
    Accepted and ignored.
  • metadata object
    Accepted and ignored (max 16 string pairs).
  • n integer
    Only 1 is supported. 1
  • max_tokens integer
    Accepted and ignored at launch (answer length is controlled by Prudai; a cut answer has finish_reason length). min. 1
  • max_completion_tokens integer
    Accepted and ignored at launch, like max_tokens. min. 1
  • logprobs boolean
    Only false is accepted; true returns 400 unsupported_parameter. false
  • response_format object
    Only {"type": "text"} is accepted; JSON modes return 400 unsupported_parameter.
  • response_format.type string verplicht
    text
  • prudai ChatPrudaiOptions
    Prudai extensions. With the OpenAI SDKs pass them via extra_body={"prudai": {...}}.
  • prudai.depth string
    Request Ultra depth. Overrides reasoning_effort. Requires the Ultra capability on your organisation (403 depth_not_permitted otherwise) and counts against the organisation’s Ultra daily quota (429 ultra_quota_exhausted when used up). Een van: ultra
  • prudai.approvals array<ChatApprovalRequest>
    Pending actions. The exact approved arguments execute through the existing human approval flow.
  • prudai.approvals[].id string verplicht
  • prudai.approvals[].level string verplicht
    Een van: confirm, review
  • prudai.approvals[].summary string verplicht
  • prudai.approvals[].operation string verplicht
  • prudai.tool_events boolean
    Stream prudai.tool progress chunks (only with stream: true). Those chunks have empty choices. standaard: false
  • prudai.knowledge_bases string or array<string>
    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 string
    patroon ^conv_[A-Za-z0-9]{20}$
  • prudai.citations string
    Whether citations are also returned as OpenAI url_citation annotations. Een van: annotations_and_prudai, prudai_only · standaard: "annotations_and_prudai"

Antwoorden

StatusBetekenis
200The completion. application/json when stream is false or absent, text/event-stream when stream is true.
202Non-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.
400Malformed request or unsupported parameter (for example client-sent tools).
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
402Not enough credits for this request, or a monthly spend cap has been reached. Only paid operations (phase 2) return it.
403Authenticated, 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).
404Unknown model, source or document.
409A request with the same Idempotency-Key is still running.
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
500Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits).
502An upstream model provider or source failed. Not charged, except work that completed before the failure (reported in details.charged_credits).
503Temporarily unavailable (maintenance, overload, or the credit check could not be performed). Nothing ran, nothing is charged.
504The request exceeded the maximum duration. Only work that completed is charged (reported in details.charged_credits).

Velden in het antwoord (200)

  • id string
    patroon ^chatcmpl-[A-Za-z0-9]{24}$
  • object string
    chat.completion
  • created integer
  • model string
    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]+)*)?$
  • choices array<ChatChoice>
  • choices[].index integer
    0
  • choices[].message AssistantMessage
  • choices[].message.role string
    assistant
  • choices[].message.content string
    The answer in Markdown. Citation markers in the text correspond to prudai.citations[].marker. kan null zijn
  • choices[].message.refusal string
    Set when the request was refused (then content is null and finish_reason is content_filter). kan null zijn
  • choices[].message.annotations array<UrlCitationAnnotation>
    OpenAI-compatible citations. Empty when prudai.citations is prudai_only.
  • choices[].finish_reason string
    stop normal end; length the answer was cut (output budget or the per-conversation cost breaker; see prudai.stop_reason); content_filter the answer was withheld by a safety boundary; approval_required means an action awaits human approval. Een van: stop, length, content_filter, approval_required
  • usage CompletionUsage
    Tokens summed over every model call Prudai made for this request, including tool rounds. Billing uses prudai.cost_credits, not a client-side token calculation.
  • usage.prompt_tokens integer
    min. 0
  • usage.completion_tokens integer
    min. 0
  • usage.total_tokens integer
    min. 0
  • usage.prompt_tokens_details object
  • usage.prompt_tokens_details.cached_tokens integer
    min. 0
  • usage.completion_tokens_details object
  • usage.completion_tokens_details.reasoning_tokens integer
    min. 0
  • prudai ChatPrudaiResult
  • prudai.conversation_id string
    patroon ^conv_[A-Za-z0-9]{20}$
  • prudai.citation_check string
    complete: every citation has a settled verified. 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 stays verified: null, for example a quote from a public source, which the audit cannot prove. Een van: complete, pending, unverifiable
  • prudai.context_truncated boolean
    Older supplied transcript content was omitted to respect the 60000-character limit.
  • prudai.notIncluded array<NotIncluded>
  • prudai.notIncluded[].reason string
    What this result does not establish or include.
  • prudai.notIncluded[].next object
    Ready call that can resolve this gap, or null if none is available. kan null zijn
  • prudai.tool_events array<PrudaiToolEvent>
  • prudai.tool_events[].event_id string
    Same id for the started and the matching completed/failed event.
  • prudai.tool_events[].status string
    Een van: started, completed, failed
  • prudai.tool_events[].source_id string
    kan null zijn
  • prudai.tool_events[].label string
  • prudai.tool_events[].result_count integer
    min. 0 · kan null zijn
  • prudai.request_id string
    patroon ^req_[A-Za-z0-9]{24}$
  • prudai.cost_credits any
    Credit charging is not activated for API chat. kan null zijn
  • prudai.price_list_version string
    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.depth DepthReport
  • prudai.depth.requested string
    Depth actually used. fast, standard, thorough correspond to reasoning_effort low, medium, high; ultra is only reachable through prudai.depth. Een van: fast, standard, thorough, ultra
  • prudai.depth.applied string
    Depth actually used. fast, standard, thorough correspond to reasoning_effort low, medium, high; ultra is only reachable through prudai.depth. Een van: fast, standard, thorough, ultra
  • prudai.depth.clamped boolean
    True when applied is lower than requested because of the model’s or organisation’s depth ceiling.

Deze lijst stopt na 40 velden.

Formaat van het antwoord: text/event-stream.

curl
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"
}
}'
CLI (binnenkort)
prudai leo chat completions