Ga naar inhoud

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.

MethodePadWat het doetStand
GET/v1/conversationsGesprekken opvragenOp productie
POST/v1/conversationsStart a conversationOp productie
GET/v1/conversations/{conversation_id}Eén gesprek opvragenOp productie
DELETE/v1/conversations/{conversation_id}Gesprek verwijderenOp productie
GET/v1/conversations/{conversation_id}/messagesBerichten van een gesprek opvragenOp productie
POST/v1/conversations/{conversation_id}/messagesSend a message in a conversationOp productie
POST/v1/conversations/{conversation_id}/restoreGesprek herstellenOp 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 query · string
    Een van: leo, leo-fiscaal, vera, bever, zia, maia
  • model query · string
    max. lengte 80
  • include_deleted query · boolean
    standaard: false
  • q query · string
    Case-insensitive title substring. Wildcard characters are treated literally. max. lengte 200
  • limit query · integer
    standaard: 100 · min. 1 · max. 200
  • after query · string
    Opaque cursor from next_cursor. Bound to the authorised selection. max. lengte 200

Antwoorden

StatusBetekenis
200One page, ordered by creation time descending with an id tie-breaker.
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.
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).
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).

Velden in data (200)

  • object string
    list
  • data array<ConversationData>
  • data[].id string
    patroon ^conv_[A-Za-z0-9]{20}$
  • data[].object string
    conversation
  • data[].product string
    Een van: leo, leo-fiscaal, vera, bever, zia, maia
  • data[].model string
    max. lengte 80
  • data[].title string
    max. lengte 500 · kan null zijn
  • data[].created_at string (date-time)
  • data[].updated_at string (date-time)
  • data[].deleted_at string (date-time)
    kan null zijn
  • data[].purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. kan null zijn
  • has_more boolean
  • next_cursor string
    max. lengte 200 · kan null zijn
curl
curl -s "https://api.prudai.com/v1/conversations" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (binnenkort)
prudai leo conversations list
Antwoord 200
{
"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-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
200Streaming conversation start (text/event-stream); the final event carries the conversation id.
201The conversation was started and the first answer completed.
202The 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.
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.

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/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"
}
}'
CLI (binnenkort)
prudai leo conversations create

Eé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_id path · string verplicht
    Opaque public API conversation id, never an internal app id. patroon ^conv_[A-Za-z0-9]{20}$

Antwoorden

StatusBetekenis
200The registered conversation metadata.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
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.
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).

Velden in data (200)

  • id string
    patroon ^conv_[A-Za-z0-9]{20}$
  • object string
    conversation
  • product string
    Een van: leo, leo-fiscaal, vera, bever, zia, maia
  • model string
    max. lengte 80
  • title string
    max. lengte 500 · kan null zijn
  • created_at string (date-time)
  • updated_at string (date-time)
  • deleted_at string (date-time)
    kan null zijn
  • purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. kan null zijn
curl
curl -s "https://api.prudai.com/v1/conversations/<conversation_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (binnenkort)
prudai leo conversations get
Antwoord 200
{
"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=true laat zien wat er zou gebeuren en slaat niets op.
  • Idempotentie: stuur Idempotency-Key mee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.
  • Verwijderen is zacht; zie Conventies.

Parameters

  • conversation_id path · string verplicht
    Opaque public API conversation id, never an internal app id. patroon ^conv_[A-Za-z0-9]{20}$
  • dryRun query · boolean
    Validate and preview the operation without changing register entries. Approval is still required. standaard: false
  • Idempotency-Key header · string verplicht
    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 header · string
    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

StatusBetekenis
200Soft-deleted entry, or unchanged metadata for a dry run.
202Human 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.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
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).

Velden in data (200)

  • id string
    patroon ^conv_[A-Za-z0-9]{20}$
  • object string
    conversation
  • product string
    Een van: leo, leo-fiscaal, vera, bever, zia, maia
  • model string
    max. lengte 80
  • title string
    max. lengte 500 · kan null zijn
  • created_at string (date-time)
  • updated_at string (date-time)
  • deleted_at string (date-time)
    kan null zijn
  • purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. kan null zijn
curl
curl -s -X DELETE "https://api.prudai.com/v1/conversations/<conversation_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"
CLI (binnenkort)
prudai leo conversations delete
Antwoord 200
{
"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_id path · string verplicht
    Opaque public API conversation id, never an internal app id. patroon ^conv_[A-Za-z0-9]{20}$
  • limit query · integer
    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 set truncated. standaard: 10 · min. 1 · max. 200
  • after query · string
    Opaque cursor from next_cursor. Bound to the authorised selection. max. lengte 200

Antwoorden

StatusBetekenis
200One bounded page of messages.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
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.
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).

Velden in data (200)

  • object string
    list
  • data array<ConversationMessage>
  • data[].role string
    Een van: user, assistant
  • data[].text string
    Message text with its original citation markers. max. lengte 200000
  • data[].citations array<ConversationCitation>
  • data[].citations[].reference string
    Public source reference from the stored audit.
  • data[].citations[].verified boolean
    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: null until disproved), also if the completion marked another, unquoted mention of it verified: 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 read null where the completion said true; a disproved citation stays false. kan null zijn
  • data[].citations[].identifier_exists boolean
    Same meaning as PrudaiCitation.identifier_exists. kan null zijn
  • data[].citations[].quote_verified boolean
    Same meaning as PrudaiCitation.quote_verified. kan null zijn
  • data[].created_at string (date-time)
  • data[].truncated boolean
    True when the text or citation projection was limited by the output budget.
  • has_more boolean
  • next_cursor string
    max. lengte 200 · kan null zijn
curl
curl -s "https://api.prudai.com/v1/conversations/<conversation_id>/messages" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (binnenkort)
prudai leo conversations-messages list
Antwoord 200
{
"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-Key mee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.

Parameters

  • conversation_id path · string verplicht
    patroon ^conv_[A-Za-z0-9]{20}$
  • 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) or, with stream: true, text/event-stream.
202The 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.
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.

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/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"
}
}'
CLI (binnenkort)
prudai leo conversations-messages create

Gesprek 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=true laat zien wat er zou gebeuren en slaat niets op.
  • Idempotentie: stuur Idempotency-Key mee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.

Parameters

  • conversation_id path · string verplicht
    Opaque public API conversation id, never an internal app id. patroon ^conv_[A-Za-z0-9]{20}$
  • dryRun query · boolean
    Validate and preview the operation without changing register entries. Approval is still required. standaard: false
  • Idempotency-Key header · string verplicht
    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 header · string
    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

StatusBetekenis
200Restored entry, or unchanged metadata for a dry run.
202Human 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.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
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.
410The restore window expired. Uses document_not_found in the standard error envelope.
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).

Velden in data (200)

  • id string
    patroon ^conv_[A-Za-z0-9]{20}$
  • object string
    conversation
  • product string
    Een van: leo, leo-fiscaal, vera, bever, zia, maia
  • model string
    max. lengte 80
  • title string
    max. lengte 500 · kan null zijn
  • created_at string (date-time)
  • updated_at string (date-time)
  • deleted_at string (date-time)
    kan null zijn
  • purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. kan null zijn
curl
curl -s -X POST "https://api.prudai.com/v1/conversations/<conversation_id>/restore" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"
CLI (binnenkort)
prudai leo conversations restore
Antwoord 200
{
"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"
}