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.
| Method | Path | What it does | State |
|---|---|---|---|
GET | /v1/knowledge-bases | List the organisation’s knowledge bases | Coming soon |
POST | /v1/knowledge-bases | Create a knowledge base | Coming soon |
GET | /v1/knowledge-bases/{kb_id} | Get one knowledge base | Coming soon |
PATCH | /v1/knowledge-bases/{kb_id} | Rename or describe a knowledge base | Coming soon |
DELETE | /v1/knowledge-bases/{kb_id} | Soft-delete a knowledge base | Coming soon |
GET | /v1/knowledge-bases/{kb_id}/documents | List documents and their processing status | Coming soon |
POST | /v1/knowledge-bases/{kb_id}/documents | Upload a document | Coming soon |
GET | /v1/knowledge-bases/{kb_id}/documents/{document_id} | Get one document with its processing status | Coming soon |
DELETE | /v1/knowledge-bases/{kb_id}/documents/{document_id} | Soft-delete a document | Coming soon |
POST | /v1/knowledge-bases/{kb_id}/documents/{document_id}/restore | Restore a soft-deleted document | Coming soon |
POST | /v1/knowledge-bases/{kb_id}/query | Query a knowledge base (retrieval hits with citations) | Coming soon |
GET | /v1/knowledge-bases/{kb_id}/register-links | List linked registers for a knowledge base | Coming soon |
POST | /v1/knowledge-bases/{kb_id}/register-links | Link an external register to a knowledge base | Coming soon |
POST | /v1/knowledge-bases/{kb_id}/restore | Restore a soft-deleted knowledge base | Coming soon |
POST | /v1/knowledge-bases/query | Query the organisation’s knowledge bases (retrieval hits with citations) | Coming soon |
DELETE | /v1/register-links/{link_id} | Soft-delete a linked register | Coming soon |
POST | /v1/register-links/{link_id}/query | Query rows from a linked register | Coming soon |
POST | /v1/register-links/{link_id}/restore | Restore a soft-deleted register link | Coming 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
max length 255include_deleted
One of:true,falselimit
default:20· min 1 · max 100cursor
max length 200
Responses
| Status | Meaning |
|---|---|
200 | Knowledge bases (page). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s "https://api.prudai.com/v1/knowledge-bases" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases listCreate 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=trueshows 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
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
Validate and show the effect without changing anything. One of:true,false
Body
JSON, required.
namerequired
max length 255description
max length 1024 · may benull
Responses
| Status | Meaning |
|---|---|
200 | Replay of the same Idempotency-Key, or a dry run. |
201 | Created. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
409 | Limit reached (knowledge_base_limit_reached). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
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" }'prudai leo knowledge-bases createGet 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_idrequired
pattern^kb_[A-Za-z0-9]{20}$include_deleted
One of:true,false
Responses
| Status | Meaning |
|---|---|
200 | The knowledge base. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases getRename 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=trueshows what would happen and stores nothing. - Concurrent changes: send
If-Matchwith the version you read.
Parameters
kb_idrequired
pattern^kb_[A-Za-z0-9]{20}$dryRun
Validate and show the effect without changing anything. One of:true,falseIf-Match
Body
JSON, required.
name
max length 255description
max length 1024 · may benull
Responses
| Status | Meaning |
|---|---|
200 | Updated, or a dry run. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
409 | Version conflict (version_conflict). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
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" }'prudai leo knowledge-bases updateSoft-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=trueshows what would happen and stores nothing. - Deleting is soft; see Conventions.
Parameters
kb_idrequired
pattern^kb_[A-Za-z0-9]{20}$dryRun
Validate and show the effect without changing anything. One of:true,false
Responses
| Status | Meaning |
|---|---|
200 | Soft-deleted, or a dry run. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s -X DELETE "https://api.prudai.com/v1/knowledge-bases/<kb_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases deleteList 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_idrequired
pattern^kb_[A-Za-z0-9]{20}$status
One of:pending,processing,completed,failedinclude_deleted
One of:true,falselimit
default:20· min 1 · max 100cursor
max length 200
Responses
| Status | Meaning |
|---|---|
200 | Documents (page). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases-documents listUpload 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=trueshows 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_idrequired
pattern^kb_[A-Za-z0-9]{20}$Idempotency-Key
Client-chosen unique key (we suggest a UUID) to make retries safe. Stored for 24 hours per credential and organisation (service key or personal token). Same key and same body: stored result is replayed and charged once. The knowledge-base operations (createKnowledgeBase,uploadKnowledgeBaseDocument) work differently: the key is bound to the organisation or knowledge base and lives as long as the object; see their descriptions. min length 8 · max length 255 · pattern^[\x21-\x7E]+$dryRun
Validate and show the effect without changing anything. One of:true,false
Body
Format: multipart/form-data.
Responses
| Status | Meaning |
|---|---|
200 | Replay of the same Idempotency-Key, or a dry run. |
201 | Uploaded; processing started. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
409 | Limit reached (knowledge_base_limit_reached). |
413 | File too large (request_too_large). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"prudai leo knowledge-bases-documents createGet 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_idrequired
pattern^kb_[A-Za-z0-9]{20}$document_idrequired
pattern^kbdoc_[A-Za-z0-9]{20}$
Responses
| Status | Meaning |
|---|---|
200 | The document. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents/<document_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases-documents getSoft-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=trueshows what would happen and stores nothing. - Deleting is soft; see Conventions.
Parameters
kb_idrequired
pattern^kb_[A-Za-z0-9]{20}$document_idrequired
pattern^kbdoc_[A-Za-z0-9]{20}$dryRun
Validate and show the effect without changing anything. One of:true,false
Responses
| Status | Meaning |
|---|---|
200 | Soft-deleted, or a dry run. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s -X DELETE "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents/<document_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases-documents deleteRestore 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=trueshows what would happen and stores nothing.
Parameters
kb_idrequired
pattern^kb_[A-Za-z0-9]{20}$document_idrequired
pattern^kbdoc_[A-Za-z0-9]{20}$dryRun
Validate and show the effect without changing anything. One of:true,false
Responses
| Status | Meaning |
|---|---|
200 | Restored, or a dry run. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/documents/<document_id>/restore" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases-documents restoreQuery 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_idrequired
pattern^kb_[A-Za-z0-9]{20}$
Body
JSON, required.
questionrequired
max length 2000top_k
default:5· min 1 · max 20
Responses
| Status | Meaning |
|---|---|
200 | Hits. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
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 }'prudai leo knowledge-bases queryList linked registers for a knowledge base
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.
Parameters
kb_idrequired
Public knowledge base id or a RAG knowledge base UUID; the same user ACL applies to both forms.include_deleted
One of:true,false· default:"false"
Responses
| Status | Meaning |
|---|---|
200 | Operation result in the standard envelope. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Link or knowledge base unavailable to this user. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | Upstream register unavailable or returned an invalid response. |
503 | Register source or Developer API not configured. |
curl -s "https://api.prudai.com/v1/knowledge-bases/<kb_id>/register-links" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases register-links listLink an external register to a knowledge base
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=trueshows what would happen and stores nothing.
Parameters
dryRun
Validate the KB manage right and preview without writing. One of:true,falsekb_idrequired
Public knowledge base id or a RAG knowledge base UUID; the same user ACL applies to both forms.
Body
JSON, required.
sourcerequired
One of:irma,ordosource_refrequired
max length 128labelrequired
max length 200
Responses
| Status | Meaning |
|---|---|
200 | Dry-run preview; no link is stored. |
201 | Operation result in the standard envelope. |
202 | Waiting for human approval through the existing approval flow. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Link or knowledge base unavailable to this user. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | Upstream register unavailable or returned an invalid response. |
503 | Register source or Developer API not configured. |
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" }'prudai leo knowledge-bases register-links createRestore 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=trueshows what would happen and stores nothing.
Parameters
kb_idrequired
pattern^kb_[A-Za-z0-9]{20}$dryRun
Validate and show the effect without changing anything. One of:true,false
Responses
| Status | Meaning |
|---|---|
200 | Restored, or a dry run. |
202 | Waiting for human approval (ApprovalRequest). |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Knowledge base or document not found in this organisation (knowledge_base_not_found, document_not_found). |
409 | Limit reached (knowledge_base_limit_reached). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
curl -s -X POST "https://api.prudai.com/v1/knowledge-bases/<kb_id>/restore" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo knowledge-bases restoreQuery 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.
questionrequired
max length 2000top_k
default:5· min 1 · max 20knowledge_bases
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, returns404 knowledge_base_not_found(never 403, so existence does not leak); a soft-deleted knowledge base is skipped and reported innotIncluded.prudai:knowledge_bases:readis needed unless the value is"none": a key without it gets403 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
| Status | Meaning |
|---|---|
200 | Hits (possibly none). provenance.knowledge_bases shows what was asked for, what applied and which knowledge bases were searched. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | A chosen knowledge base does not exist in this organisation (knowledge_base_not_found, param: knowledge_bases). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | The knowledge base service (RAG) failed for every chosen knowledge base (upstream_error). |
503 | Knowledge bases are not configured yet (service_unavailable) or the Developer API is off. |
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" }'prudai leo knowledge-bases query-allSoft-delete a linked register
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=trueshows what would happen and stores nothing. - Deleting is soft; see Conventions.
Parameters
dryRun
Validate the KB manage right and preview without writing. One of:true,falselink_idrequired
Responses
| Status | Meaning |
|---|---|
200 | Operation result in the standard envelope. |
202 | Waiting for human approval through the existing approval flow. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Link or knowledge base unavailable to this user. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | Upstream register unavailable or returned an invalid response. |
503 | Register source or Developer API not configured. |
curl -s -X DELETE "https://api.prudai.com/v1/register-links/<link_id>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo register-links deleteQuery rows from a linked register
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.
Parameters
link_idrequired
Body
JSON, required.
filter
default:{}sortsort.fieldrequired
max length 128sort.directionrequired
One of:asc,desccursor
pattern^\d{1,7}$limit
default:50· min 1 · max 200aggregateaggregate.operationrequired
One of:count,sum,avg,min,maxaggregate.field
max length 128
Responses
| Status | Meaning |
|---|---|
200 | Operation result in the standard envelope. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Link or knowledge base unavailable to this user. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | Upstream register unavailable or returned an invalid response. |
503 | Register source or Developer API not configured. |
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" } }'prudai leo register-links queryRestore a soft-deleted register link
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=trueshows what would happen and stores nothing.
Parameters
dryRun
Validate the KB manage right and preview without writing. One of:true,falselink_idrequired
Responses
| Status | Meaning |
|---|---|
200 | Operation result in the standard envelope. |
202 | Waiting for human approval through the existing approval flow. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Link or knowledge base unavailable to this user. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
429 | Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded. |
502 | Upstream register unavailable or returned an invalid response. |
503 | Register source or Developer API not configured. |
curl -s -X POST "https://api.prudai.com/v1/register-links/<link_id>/restore" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo register-links restore