Skip to content

Prudai Developer API: knowledge bases

The operations of this part (Knowledge bases).

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/knowledge-basesList the organisation’s knowledge basesComing soon
POST/v1/knowledge-basesCreate a knowledge baseComing soon
GET/v1/knowledge-bases/{kb_id}Get one knowledge baseComing soon
PATCH/v1/knowledge-bases/{kb_id}Rename or describe a knowledge baseComing soon
DELETE/v1/knowledge-bases/{kb_id}Soft-delete a knowledge baseComing soon
GET/v1/knowledge-bases/{kb_id}/documentsList documents and their processing statusComing soon
POST/v1/knowledge-bases/{kb_id}/documentsUpload a documentComing soon
GET/v1/knowledge-bases/{kb_id}/documents/{document_id}Get one document with its processing statusComing soon
DELETE/v1/knowledge-bases/{kb_id}/documents/{document_id}Soft-delete a documentComing soon
POST/v1/knowledge-bases/{kb_id}/documents/{document_id}/restoreRestore a soft-deleted documentComing soon
POST/v1/knowledge-bases/{kb_id}/queryQuery a knowledge base (retrieval hits with citations)Coming soon
GET/v1/knowledge-bases/{kb_id}/register-linksList linked registers for a knowledge baseComing soon
POST/v1/knowledge-bases/{kb_id}/register-linksLink an external register to a knowledge baseComing soon
POST/v1/knowledge-bases/{kb_id}/restoreRestore a soft-deleted knowledge baseComing soon
POST/v1/knowledge-bases/queryQuery the organisation’s knowledge bases (retrieval hits with citations)Coming soon
DELETE/v1/register-links/{link_id}Soft-delete a linked registerComing soon
POST/v1/register-links/{link_id}/queryQuery rows from a linked registerComing soon
POST/v1/register-links/{link_id}/restoreRestore a soft-deleted register linkComing soon

List the organisation's knowledge bases

GET /v1/knowledge-bases

Knowledge bases of the organisation that owns the key, newest first. Soft-deleted ones only with include_deleted=true. q filters on the name.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:read
  • Approval: none, no extra step.

Parameters

  • q query · string
    max length 255
  • include_deleted query · string
    One of: true, false
  • limit query · integer
    default: 20 · min 1 · max 100
  • cursor query · string
    max length 200

Responses

StatusMeaning
200Knowledge bases (page).
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.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s "https://api.prudai.com/v1/knowledge-bases" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases list

Create a knowledge base

POST /v1/knowledge-bases

Creates an empty knowledge base for the organisation that owns the key. Limit: 50 active knowledge bases per organisation (409 knowledge_base_limit_reached). Waits for a human (confirm).

Idempotency (differs from the chat and source operations). Idempotency-Key is required (8 to 255 characters). The key belongs to the organisation, not to the credential, and does not expire while the knowledge base exists. A replay with the same name and description returns the knowledge base as it is now with 200 (the first answer was 201); it is not a stored copy of the first response and carries no Idempotent-Replayed header. The same key with other content gets 422 idempotency_key_reused. A concurrent request with the same key returns the winner.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases: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

  • 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]+$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false

Body

JSON, required.

  • name string required
    max length 255
  • description string
    max length 1024 · may be null

Responses

StatusMeaning
200Replay of the same Idempotency-Key, or a dry run.
201Created.
202Waiting for human approval (ApprovalRequest).
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).
409Limit reached (knowledge_base_limit_reached).
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.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"description": "string"
}'
CLI (coming soon)
prudai leo knowledge-bases create

Get one knowledge base

GET /v1/knowledge-bases/{kb_id}

One knowledge base of the organisation. Another organisation’s id answers 404.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:read
  • Approval: none, no extra step.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • include_deleted query · string
    One of: true, false

Responses

StatusMeaning
200The knowledge base.
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases get

Rename or describe a knowledge base

PATCH /v1/knowledge-bases/{kb_id}

Optimistic concurrency: send If-Match: "<version>" from the last read; a stale version answers 409 version_conflict (not 412: the platform uses 409 for every version conflict, so a client has one code to handle). Without If-Match the current version is assumed. Waits for a human (confirm).

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:write
  • Approval: confirm, the user confirms exactly this call.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • Concurrent changes: send If-Match with the version you read.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false
  • If-Match header · string

Body

JSON, required.

  • name string
    max length 255
  • description string
    max length 1024 · may be null

Responses

StatusMeaning
200Updated, or a dry run.
202Waiting for human approval (ApprovalRequest).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
409Version conflict (version_conflict).
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.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X PATCH "https://api.prudai.com/v1/knowledge-bases/<kb_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"description": "string"
}'
CLI (coming soon)
prudai leo knowledge-bases update

Soft-delete a knowledge base

DELETE /v1/knowledge-bases/{kb_id}

Soft delete: the knowledge base disappears from lists, queries and document routes and can be restored with restoreKnowledgeBase for 30 days. After that a cleanup job removes the RAG index, the files and the register row for good (with an audit line of ids and counts); a purged knowledge base answers 404. Waits for a human (review).

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:delete
  • Approval: review, a second person or role approves.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • Deleting is soft; see Conventions.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false

Responses

StatusMeaning
200Soft-deleted, or a dry run.
202Waiting for human approval (ApprovalRequest).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X DELETE "https://api.prudai.com/v1/knowledge-bases/<kb_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases delete

List documents and their processing status

GET /v1/knowledge-bases/{kb_id}/documents

Documents of the knowledge base with their live processing status from RAG (pending, processing, completed, failed). With status the total is null (the filter applies after paging).

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:read
  • Approval: none, no extra step.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • status query · string
    One of: pending, processing, completed, failed
  • include_deleted query · string
    One of: true, false
  • limit query · integer
    default: 20 · min 1 · max 100
  • cursor query · string
    max length 200

Responses

StatusMeaning
200Documents (page).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
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.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases-documents list

Upload a document

POST /v1/knowledge-bases/{kb_id}/documents

Multipart upload with exactly one field file (max 25 MB; pdf, docx, doc, odt, rtf, txt, md, html, csv, xlsx, pptx, eml). Processing is asynchronous: poll getKnowledgeBaseDocument (in next) until status is completed. Limit: 1,000 active documents per knowledge base. Waits for a human (confirm).

Idempotency (differs from the chat and source operations). Idempotency-Key is required (8 to 255 characters). The key belongs to the knowledge base and does not expire while the document exists. A replay with the same filename and size returns the document as it is now with 200 (the first answer was 201), without Idempotent-Replayed; the same key with another file gets 422 idempotency_key_reused. A concurrent upload with the same key returns the winner and the loser’s bytes are removed again.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases: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

  • kb_id path · string required
    pattern ^kb_[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]+$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false

Body

Format: multipart/form-data.

Responses

StatusMeaning
200Replay of the same Idempotency-Key, or a dry run.
201Uploaded; processing started.
202Waiting for human approval (ApprovalRequest).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
409Limit reached (knowledge_base_limit_reached).
413File too large (request_too_large).
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.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"
CLI (coming soon)
prudai leo knowledge-bases-documents create

Get one document with its processing status

GET /v1/knowledge-bases/{kb_id}/documents/{document_id}

Metadata and live processing status of one document.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:read
  • Approval: none, no extra step.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • document_id path · string required
    pattern ^kbdoc_[A-Za-z0-9]{20}$

Responses

StatusMeaning
200The document.
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents/<document_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases-documents get

Soft-delete a document

DELETE /v1/knowledge-bases/{kb_id}/documents/{document_id}

The document disappears from lists and query hits and can be restored for 30 days; after that the cleanup job removes the RAG index entry and the file for good. Waits for a human (review).

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:delete
  • Approval: review, a second person or role approves.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • Deleting is soft; see Conventions.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • document_id path · string required
    pattern ^kbdoc_[A-Za-z0-9]{20}$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false

Responses

StatusMeaning
200Soft-deleted, or a dry run.
202Waiting for human approval (ApprovalRequest).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X DELETE "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents/<document_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases-documents delete

Restore a soft-deleted document

POST /v1/knowledge-bases/{kb_id}/documents/{document_id}/restore

Undoes a soft delete; no re-indexing needed. Waits for a human (confirm).

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:write
  • Approval: confirm, the user confirms exactly this call.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • document_id path · string required
    pattern ^kbdoc_[A-Za-z0-9]{20}$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false

Responses

StatusMeaning
200Restored, or a dry run.
202Waiting for human approval (ApprovalRequest).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents/<document_id>/restore" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases-documents restore

Query a knowledge base (retrieval hits with citations)

POST /v1/knowledge-bases/{kb_id}/query

Returns the most relevant passages (content) with their knowledge base (knowledge_base_id) and document (document_id, filename) as citation. No page number or score yet (RAG does not hand them over). No generated answer (see answerFromKnowledgeBase). To query several knowledge bases at once see queryKnowledgeBases. Free; 60 queries per minute per key.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:read
  • Approval: none, no extra step.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$

Body

JSON, required.

  • question string required
    max length 2000
  • top_k integer
    default: 5 · min 1 · max 20

Responses

StatusMeaning
200Hits.
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
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.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/query" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"question": "string",
"top_k": 5
}'
CLI (coming soon)
prudai leo knowledge-bases query

GET /v1/knowledge-bases/{kb_id}/register-links

Lists active links. Set include_deleted=true to include recoverable soft-deleted links. Knowledge base read access is checked as the signed-in user.

  • State: coming soon, not in production yet.
  • Scope: prudai:register_links:read
  • Approval: none, no extra step.
  • kb_id path · string required
    Public knowledge base id or a RAG knowledge base UUID; the same user ACL applies to both forms.
  • include_deleted query · string
    One of: true, false · default: "false"
StatusMeaning
200Operation result in the standard envelope.
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).
404Link or knowledge base unavailable to this user.
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.
502Upstream register unavailable or returned an invalid response.
503Register source or Developer API not configured.
curl
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>/register-links" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases register-links list

POST /v1/knowledge-bases/{kb_id}/register-links

Requires knowledge base management rights and human confirmation. Stores a link only; register rows stay in IRMA or ORDO. The server derives the actor and organisation from the authenticated user.

  • State: coming soon, not in production yet.
  • Scope: prudai:register_links:write
  • Approval: confirm, the user confirms exactly this call.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • dryRun query · string
    Validate the KB manage right and preview without writing. One of: true, false
  • kb_id path · string required
    Public knowledge base id or a RAG knowledge base UUID; the same user ACL applies to both forms.

JSON, required.

  • source string required
    One of: irma, ordo
  • source_ref string required
    max length 128
  • label string required
    max length 200
StatusMeaning
200Dry-run preview; no link is stored.
201Operation result in the standard envelope.
202Waiting for human approval through the existing approval flow.
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).
404Link or knowledge base unavailable to this user.
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.
502Upstream register unavailable or returned an invalid response.
503Register source or Developer API not configured.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/register-links" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"source": "irma",
"source_ref": "string",
"label": "string"
}'
CLI (coming soon)
prudai leo knowledge-bases register-links create

Restore a soft-deleted knowledge base

POST /v1/knowledge-bases/{kb_id}/restore

Undoes a soft delete. Waits for a human (confirm).

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:write
  • Approval: confirm, the user confirms exactly this call.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.

Parameters

  • kb_id path · string required
    pattern ^kb_[A-Za-z0-9]{20}$
  • dryRun query · string
    Validate and show the effect without changing anything. One of: true, false

Responses

StatusMeaning
200Restored, or a dry run.
202Waiting for human approval (ApprovalRequest).
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).
404Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found).
409Limit reached (knowledge_base_limit_reached).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
502The knowledge base service (RAG) failed (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/restore" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo knowledge-bases restore

Query the organisation's knowledge bases (retrieval hits with citations)

POST /v1/knowledge-bases/query

Like queryKnowledgeBase, but over several knowledge bases at once: POST /v1/knowledge-bases/query (the path of one knowledge base is /v1/knowledge-bases/{kb_id}/query). Which ones is the knowledge_bases field (default "all", see KnowledgeBaseSelection). Hits come back with the knowledge base (knowledge_base_id) and document (document_id, filename) as citation. RAG gives no score that is comparable across knowledge bases, so hits of different knowledge bases are interleaved by rank. A knowledge base that does not answer is left out and reported in notIncluded (all failing gives 502). Each knowledge base contributes at most top_k hits and the merged list is cut at top_k; with a low top_k a knowledge base can therefore be missing, and completeness.truncated is then true with a line in notIncluded. With "none" the result is empty. Free; one call counts as one query in the 60-per-minute limit per key, however many knowledge bases it spans.

  • State: coming soon, not in production yet.
  • Scope: prudai:knowledge_bases:read
  • Approval: none, no extra step.

Body

JSON, required.

  • question string required
    max length 2000
  • top_k integer
    default: 5 · min 1 · max 20
  • knowledge_bases string or array<string>
    Which of your organisation’s own knowledge bases take part in a request that searches or generates "all" is the default, also when the field is missing: every active knowledge base of the organisation. "none": no knowledge base (public sources only). An array: exactly these public ids (kb_..., 1 to 50, duplicates ignored). The choice is always limited to the organisation of the key. An unknown id, or an id of another organisation, returns 404 knowledge_base_not_found (never 403, so existence does not leak); a soft-deleted knowledge base is skipped and reported in notIncluded. prudai:knowledge_bases:read is needed unless the value is "none": a key without it gets 403 insufficient_scope, also when it leaves the field out (that means "all"). Send "none" to run without knowledge bases. The knowledge-base query operations themselves always require the scope, whatever the value. default: "all"

Responses

StatusMeaning
200Hits (possibly none). provenance.knowledge_bases shows what was asked for, what applied and which knowledge bases were searched.
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).
404A chosen knowledge base does not exist in this organisation (knowledge_base_not_found, param: knowledge_bases).
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.
502The knowledge base service (RAG) failed for every chosen knowledge base (upstream_error).
503Knowledge bases are not configured yet (service_unavailable) or the Developer API is off.
curl
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/query" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"question": "string",
"top_k": 5,
"knowledge_bases": "all"
}'
CLI (coming soon)
prudai leo knowledge-bases query-all

DELETE /v1/register-links/{link_id}

Requires knowledge base management rights and human review with a reason. Soft-deletes the link without deleting upstream rows; restore it with restoreRegisterLink.

  • State: coming soon, not in production yet.
  • Scope: prudai:register_links:delete
  • Approval: review, a second person or role approves.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • Deleting is soft; see Conventions.
  • dryRun query · string
    Validate the KB manage right and preview without writing. One of: true, false
  • link_id path · string (uuid) required
StatusMeaning
200Operation result in the standard envelope.
202Waiting for human approval through the existing approval flow.
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).
404Link or knowledge base unavailable to this user.
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.
502Upstream register unavailable or returned an invalid response.
503Register source or Developer API not configured.
curl
curl -s -X DELETE "https://api.prudai.com/v1/register-links/<link_id>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo register-links delete

POST /v1/register-links/{link_id}/query

Requires a user Keycloak access token obtained through product token exchange. Service keys and personal API tokens are refused; no service identity or impersonation is used upstream. IRMA or ORDO enforces the user’s register access on every call; an upstream 403 remains a 403 without rows. Passes filters and sorting to the source. Returns source, sourceRef, filter, rows and count, with nextCursor for another page. If a source cannot aggregate, computes over at most 5,000 fetched rows and reports “berekend over N opgehaalde rijen”; larger results fail explicitly without silent truncation.

  • State: coming soon, not in production yet.
  • Scope: prudai:register_links:read
  • Approval: none, no extra step.
  • link_id path · string (uuid) required

JSON, required.

  • filter object
    default: {}
  • sort object
  • sort.field string required
    max length 128
  • sort.direction string required
    One of: asc, desc
  • cursor string
    pattern ^\d{1,7}$
  • limit integer
    default: 50 · min 1 · max 200
  • aggregate object
  • aggregate.operation string required
    One of: count, sum, avg, min, max
  • aggregate.field string
    max length 128
StatusMeaning
200Operation result in the standard envelope.
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).
404Link or knowledge base unavailable to this user.
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.
502Upstream register unavailable or returned an invalid response.
503Register source or Developer API not configured.
curl
curl -s -X POST "https://api.prudai.com/v1/register-links/<link_id>/query" \
-H "Authorization: Bearer $PRUDAI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filter": {},
"sort": {
"field": "string",
"direction": "asc"
},
"cursor": "string",
"limit": 50,
"aggregate": {
"operation": "count",
"field": "string"
}
}'
CLI (coming soon)
prudai leo register-links query

POST /v1/register-links/{link_id}/restore

Requires knowledge base management rights and human confirmation. Restores the same link; upstream access is checked again when querying.

  • State: coming soon, not in production yet.
  • Scope: prudai:register_links:write
  • Approval: confirm, the user confirms exactly this call.
  • Dry run: ?dryRun=true shows what would happen and stores nothing.
  • dryRun query · string
    Validate the KB manage right and preview without writing. One of: true, false
  • link_id path · string (uuid) required
StatusMeaning
200Operation result in the standard envelope.
202Waiting for human approval through the existing approval flow.
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).
404Link or knowledge base unavailable to this user.
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.
502Upstream register unavailable or returned an invalid response.
503Register source or Developer API not configured.
curl
curl -s -X POST "https://api.prudai.com/v1/register-links/<link_id>/restore" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo register-links restore