Skip to content

Prudai Developer API: conversations

Reading conversations, and deleting softly and restoring them.

Base URL https://api.prudai.com/v1. Logging in is in Login, scopes in Scopes and permissions, errors in Errors. Overview.

MethodPathWhat it doesState
GET/v1/conversationsList API conversationsIn production
POST/v1/conversationsStart a conversationIn production
GET/v1/conversations/{conversation_id}Get an API conversationIn production
DELETE/v1/conversations/{conversation_id}Soft delete an API conversationIn production
GET/v1/conversations/{conversation_id}/messagesList API conversation messagesIn production
POST/v1/conversations/{conversation_id}/messagesSend a message in a conversationIn production
POST/v1/conversations/{conversation_id}/restoreRestore a soft-deleted API conversationIn production

List API conversations

GET /v1/conversations

Lists only conversations registered through this API in the calling organisation. Personal credentials see only their subject’s conversations; service credentials see all registered conversations of their organisation. App-only conversations are excluded. Deleted entries are hidden unless include_deleted is true and the credential also has an explicit conversations write or delete scope.

  • State: in production.
  • Scope: prudai:conversations:read
  • Approval: none, no extra step.

Parameters

  • product query · string
    One of: leo, leo-fiscaal, vera, bever, zia, maia
  • model query · string
    max length 80
  • include_deleted query · boolean
    default: false
  • q query · string
    Case-insensitive title substring. Wildcard characters are treated literally. max length 200
  • limit query · integer
    default: 100 · min 1 · max 200
  • after query · string
    Opaque cursor from next_cursor. Bound to the authorised selection. max length 200

Responses

StatusMeaning
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).

Fields in data (200)

  • object string
    list
  • data array<ConversationData>
  • data[].id string
    pattern ^conv_[A-Za-z0-9]{20}$
  • data[].object string
    conversation
  • data[].product string
    One of: leo, leo-fiscaal, vera, bever, zia, maia
  • data[].model string
    max length 80
  • data[].title string
    max length 500 · may be null
  • data[].created_at string (date-time)
  • data[].updated_at string (date-time)
  • data[].deleted_at string (date-time)
    may be null
  • data[].purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. may be null
  • has_more boolean
  • next_cursor string
    max length 200 · may be null
curl
curl -s "https://api.prudai.com/v1/conversations" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo conversations list
Response 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.

  • State: in production.
  • Scope: prudai:chat:read
  • Approval: none, no extra step.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.

Parameters

  • Idempotency-Key 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 length 8 · max length 255 · pattern ^[\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 length 128 · pattern ^[\x21-\x7E]+$

Body

JSON, required.

  • model string required
    A product, optionally followed by / and a specialisation slug (e.g. leo/arbeidsrecht). max length 80 · pattern ^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$
  • messages array<object> required
  • stream boolean
    default: false
  • stream_options StreamOptions
  • stream_options.include_usage boolean
    Send a final chunk with usage and empty choices before [DONE]. default: 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. One of: 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 length 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 required
    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). One of: ultra
  • prudai.approvals array<ChatApprovalRequest>
    Pending actions. The exact approved arguments execute through the existing human approval flow.
  • prudai.approvals[].id string required
  • prudai.approvals[].level string required
    One of: confirm, review
  • prudai.approvals[].summary string required
  • prudai.approvals[].operation string required
  • prudai.tool_events boolean
    Stream prudai.tool progress chunks (only with stream: true). Those chunks have empty choices. default: 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
    pattern ^conv_[A-Za-z0-9]{20}$
  • prudai.citations string
    Whether citations are also returned as OpenAI url_citation annotations. One of: annotations_and_prudai, prudai_only · default: "annotations_and_prudai"

Responses

StatusMeaning
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.

Fields in the response (200)

  • id string
    pattern ^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 length 80 · pattern ^(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. may be null
  • choices[].message.refusal string
    Set when the request was refused (then content is null and finish_reason is content_filter). may be null
  • 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. One of: 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
    pattern ^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. One of: 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. may be null
  • 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
    One of: started, completed, failed
  • prudai.tool_events[].source_id string
    may be null
  • prudai.tool_events[].label string
  • prudai.tool_events[].result_count integer
    min 0 · may be null
  • prudai.request_id string
    pattern ^req_[A-Za-z0-9]{24}$
  • prudai.cost_credits any
    Credit charging is not activated for API chat. may be null
  • 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. One of: 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. One of: 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.

This list stops after 40 fields.

Response format: 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 (coming soon)
prudai leo conversations create

Get an API conversation

GET /v1/conversations/{conversation_id}

Unknown, deleted, foreign-organisation and other users’ personal conversations return 404 document_not_found without disclosing their existence.

  • State: in production.
  • Scope: prudai:conversations:read
  • Approval: none, no extra step.

Parameters

  • conversation_id path · string required
    Opaque public API conversation id, never an internal app id. pattern ^conv_[A-Za-z0-9]{20}$

Responses

StatusMeaning
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).

Fields in data (200)

  • id string
    pattern ^conv_[A-Za-z0-9]{20}$
  • object string
    conversation
  • product string
    One of: leo, leo-fiscaal, vera, bever, zia, maia
  • model string
    max length 80
  • title string
    max length 500 · may be null
  • created_at string (date-time)
  • updated_at string (date-time)
  • deleted_at string (date-time)
    may be null
  • purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. may be null
curl
curl -s "https://api.prudai.com/v1/conversations/<conversation_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo conversations get
Response 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"
}

Soft delete an API conversation

DELETE /v1/conversations/{conversation_id}

Hides the API register entry from lists, gets and chat continuation. The underlying app conversation and messages remain subject to the existing retention policy. This does not call the app’s separate delete operation or remove any content. Returns 202 with an approval request until a human approves. dryRun=true previews unchanged metadata without modifying the register. Unknown or foreign conversations return 404 document_not_found before approval is requested.

  • State: in production.
  • Scope: prudai:conversations:delete
  • Approval: review, a second person or role approves.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.
  • Deleting is soft; see Conventions.

Parameters

  • conversation_id path · string required
    Opaque public API conversation id, never an internal app id. pattern ^conv_[A-Za-z0-9]{20}$
  • dryRun query · boolean
    Validate and preview the operation without changing register entries. Approval is still required. default: false
  • Idempotency-Key header · string required
    Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern ^[\x21-\x7E]+$
  • x-prudai-approval 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. pattern ^apr_[A-Za-z0-9]{24}$

Responses

StatusMeaning
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).

Fields in data (200)

  • id string
    pattern ^conv_[A-Za-z0-9]{20}$
  • object string
    conversation
  • product string
    One of: leo, leo-fiscaal, vera, bever, zia, maia
  • model string
    max length 80
  • title string
    max length 500 · may be null
  • created_at string (date-time)
  • updated_at string (date-time)
  • deleted_at string (date-time)
    may be null
  • purge_after string (date-time)
    Restore deadline for a deleted entry, not a promise of content deletion. may be null
curl
curl -s -X DELETE "https://api.prudai.com/v1/conversations/<conversation_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"
CLI (coming soon)
prudai leo conversations delete
Response 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"
}

List API conversation messages

GET /v1/conversations/{conversation_id}/messages

Returns user and assistant text in chronological order, retaining citation markers. Tool and system rows and all internal message and conversation ids are excluded. verified, identifier_exists and quote_verified come from the stored citation audit, with the same meaning as in a completion; citations is empty until that audit has run. Each text is limited to 200000 characters and carries truncated. A page has at most 200 messages; the complete response is bounded to 1 MiB, so a page may contain fewer messages. The text budget per message depends on the requested page limit; requesting a smaller page allows longer text. Omitted audit data or citation projection also sets truncated. The next call advances past the last returned message and always terminates.

  • State: in production.
  • Scope: prudai:conversations:read
  • Approval: none, no extra step.

Parameters

  • conversation_id path · string required
    Opaque public API conversation id, never an internal app id. pattern ^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. default: 10 · min 1 · max 200
  • after query · string
    Opaque cursor from next_cursor. Bound to the authorised selection. max length 200

Responses

StatusMeaning
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).

Fields in data (200)

  • object string
    list
  • data array<ConversationMessage>
  • data[].role string
    One of: user, assistant
  • data[].text string
    Message text with its original citation markers. max length 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. may be null
  • data[].citations[].identifier_exists boolean
    Same meaning as PrudaiCitation.identifier_exists. may be null
  • data[].citations[].quote_verified boolean
    Same meaning as PrudaiCitation.quote_verified. may be null
  • 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 length 200 · may be null
curl
curl -s "https://api.prudai.com/v1/conversations/<conversation_id>/messages" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo conversations-messages list
Response 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.

  • State: in production.
  • Scope: prudai:chat:read
  • Approval: none, no extra step.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.

Parameters

  • conversation_id path · string required
    pattern ^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 length 8 · max length 255 · pattern ^[\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 length 128 · pattern ^[\x21-\x7E]+$

Body

JSON, required.

  • model string required
    A product, optionally followed by / and a specialisation slug (e.g. leo/arbeidsrecht). max length 80 · pattern ^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$
  • messages array<object> required
  • stream boolean
    default: false
  • stream_options StreamOptions
  • stream_options.include_usage boolean
    Send a final chunk with usage and empty choices before [DONE]. default: 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. One of: 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 length 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 required
    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). One of: ultra
  • prudai.approvals array<ChatApprovalRequest>
    Pending actions. The exact approved arguments execute through the existing human approval flow.
  • prudai.approvals[].id string required
  • prudai.approvals[].level string required
    One of: confirm, review
  • prudai.approvals[].summary string required
  • prudai.approvals[].operation string required
  • prudai.tool_events boolean
    Stream prudai.tool progress chunks (only with stream: true). Those chunks have empty choices. default: 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
    pattern ^conv_[A-Za-z0-9]{20}$
  • prudai.citations string
    Whether citations are also returned as OpenAI url_citation annotations. One of: annotations_and_prudai, prudai_only · default: "annotations_and_prudai"

Responses

StatusMeaning
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.

Fields in the response (200)

  • id string
    pattern ^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 length 80 · pattern ^(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. may be null
  • choices[].message.refusal string
    Set when the request was refused (then content is null and finish_reason is content_filter). may be null
  • 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. One of: 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
    pattern ^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. One of: 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. may be null
  • 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
    One of: started, completed, failed
  • prudai.tool_events[].source_id string
    may be null
  • prudai.tool_events[].label string
  • prudai.tool_events[].result_count integer
    min 0 · may be null
  • prudai.request_id string
    pattern ^req_[A-Za-z0-9]{24}$
  • prudai.cost_credits any
    Credit charging is not activated for API chat. may be null
  • 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. One of: 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. One of: 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.

This list stops after 40 fields.

Response format: 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 (coming soon)
prudai leo conversations-messages create

Restore a soft-deleted API conversation

POST /v1/conversations/{conversation_id}/restore

Restores the register entry only before purge_after. An expired restore returns 410 document_not_found; foreign or unknown entries return 404 document_not_found. Restoring an active entry is safe and returns its current metadata. Returns 202 with an approval request until a human approves. dryRun=true previews unchanged metadata without modifying the register. Idempotency is stored for 24 hours per organisation and operation, including the conversation and dry-run choice in the request fingerprint. A replay returns the stored result; a concurrent request returns 409 idempotency_request_in_progress; a changed request with the same key returns 422 idempotency_key_reused.

  • State: in production.
  • Scope: prudai:conversations:write
  • Approval: confirm, the user confirms exactly this call.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.

Parameters

  • conversation_id path · string required
    Opaque public API conversation id, never an internal app id. pattern ^conv_[A-Za-z0-9]{20}$
  • dryRun query · boolean
    Validate and preview the operation without changing register entries. Approval is still required. default: false
  • Idempotency-Key header · string required
    Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern ^[\x21-\x7E]+$
  • x-prudai-approval 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. pattern ^apr_[A-Za-z0-9]{24}$

Responses

StatusMeaning
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).

Fields in data (200)

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