Ga naar inhoud

Prudai Developer API: kennisbanken

Knowledge bases of the organisation and their documents; read includes retrieval queries.

Basis-URL https://api.prudai.com/v1. Inloggen staat in Inloggen, scopes in Scopes en rechten, fouten in Fouten. Overzicht.

MethodePadWat het doetStand
GET/v1/knowledge-basesList the organisation’s knowledge basesBinnenkort
POST/v1/knowledge-basesCreate a knowledge baseBinnenkort
GET/v1/knowledge-bases/{kb_id}Get one knowledge baseBinnenkort
PATCH/v1/knowledge-bases/{kb_id}Rename or describe a knowledge baseBinnenkort
DELETE/v1/knowledge-bases/{kb_id}Soft-delete a knowledge baseBinnenkort
GET/v1/knowledge-bases/{kb_id}/documentsList documents and their processing statusBinnenkort
POST/v1/knowledge-bases/{kb_id}/documentsUpload a documentBinnenkort
GET/v1/knowledge-bases/{kb_id}/documents/{document_id}Get one document with its processing statusBinnenkort
DELETE/v1/knowledge-bases/{kb_id}/documents/{document_id}Soft-delete a documentBinnenkort
POST/v1/knowledge-bases/{kb_id}/documents/{document_id}/restoreRestore a soft-deleted documentBinnenkort
POST/v1/knowledge-bases/{kb_id}/queryQuery a knowledge base (retrieval hits with citations)Binnenkort
GET/v1/knowledge-bases/{kb_id}/register-linksList linked registers for a knowledge baseBinnenkort
POST/v1/knowledge-bases/{kb_id}/register-linksLink an external register to a knowledge baseBinnenkort
POST/v1/knowledge-bases/{kb_id}/restoreRestore a soft-deleted knowledge baseBinnenkort
POST/v1/knowledge-bases/queryQuery the organisation’s knowledge bases (retrieval hits with citations)Binnenkort
DELETE/v1/register-links/{link_id}Soft-delete a linked registerBinnenkort
POST/v1/register-links/{link_id}/queryQuery rows from a linked registerBinnenkort
POST/v1/register-links/{link_id}/restoreRestore a soft-deleted register linkBinnenkort

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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:read
  • Goedkeuring: none, geen extra stap.

Parameters

  • q query · string
    max. lengte 255
  • include_deleted query · string
    Een van: true, false
  • limit query · integer
    standaard: 20 · min. 1 · max. 100
  • cursor query · string
    max. lengte 200

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • Idempotentie: stuur Idempotency-Key mee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.

Parameters

  • Idempotency-Key header · string
    Client-chosen unique key (we suggest a UUID) to make retries safe. Stored for 24 hours per credential and organisation (service key or personal token). Same key and same body: stored result is replayed and charged once. The knowledge-base operations (createKnowledgeBase, uploadKnowledgeBaseDocument) work differently: the key is bound to the organisation or knowledge base and lives as long as the object; see their descriptions. min. lengte 8 · max. lengte 255 · patroon ^[\x21-\x7E]+$
  • dryRun query · string
    Validate and show the effect without changing anything. Een van: true, false

Body

JSON, verplicht.

  • name string verplicht
    max. lengte 255
  • description string
    max. lengte 1024 · kan null zijn

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:read
  • Goedkeuring: none, geen extra stap.

Parameters

  • kb_id path · string verplicht
    patroon ^kb_[A-Za-z0-9]{20}$
  • include_deleted query · string
    Een van: true, false

Antwoorden

StatusBetekenis
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 (binnenkort)
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).

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • Gelijktijdig wijzigen: stuur If-Match mee met de versie die je las.

Parameters

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

Body

JSON, verplicht.

  • name string
    max. lengte 255
  • description string
    max. lengte 1024 · kan null zijn

Antwoorden

StatusBetekenis
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 (binnenkort)
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).

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:delete
  • Goedkeuring: review, een tweede persoon of rol keurt goed.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • Verwijderen is zacht; zie Conventies.

Parameters

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

Antwoorden

StatusBetekenis
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 (binnenkort)
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).

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:read
  • Goedkeuring: none, geen extra stap.

Parameters

  • kb_id path · string verplicht
    patroon ^kb_[A-Za-z0-9]{20}$
  • status query · string
    Een van: pending, processing, completed, failed
  • include_deleted query · string
    Een van: true, false
  • limit query · integer
    standaard: 20 · min. 1 · max. 100
  • cursor query · string
    max. lengte 200

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • Idempotentie: stuur Idempotency-Key mee; dezelfde sleutel met dezelfde body voert de actie niet twee keer uit.

Parameters

  • kb_id path · string verplicht
    patroon ^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. lengte 8 · max. lengte 255 · patroon ^[\x21-\x7E]+$
  • dryRun query · string
    Validate and show the effect without changing anything. Een van: true, false

Body

Formaat: multipart/form-data.

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:read
  • Goedkeuring: none, geen extra stap.

Parameters

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

Antwoorden

StatusBetekenis
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 (binnenkort)
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).

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:delete
  • Goedkeuring: review, een tweede persoon of rol keurt goed.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • Verwijderen is zacht; zie Conventies.

Parameters

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

Antwoorden

StatusBetekenis
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 (binnenkort)
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).

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.

Parameters

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

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:read
  • Goedkeuring: none, geen extra stap.

Parameters

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

Body

JSON, verplicht.

  • question string verplicht
    max. lengte 2000
  • top_k integer
    standaard: 5 · min. 1 · max. 20

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:register_links:read
  • Goedkeuring: none, geen extra stap.
  • kb_id path · string verplicht
    Public knowledge base id or a RAG knowledge base UUID; the same user ACL applies to both forms.
  • include_deleted query · string
    Een van: true, false · standaard: "false"
StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:register_links:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • dryRun query · string
    Validate the KB manage right and preview without writing. Een van: true, false
  • kb_id path · string verplicht
    Public knowledge base id or a RAG knowledge base UUID; the same user ACL applies to both forms.

JSON, verplicht.

  • source string verplicht
    Een van: irma, ordo
  • source_ref string verplicht
    max. lengte 128
  • label string verplicht
    max. lengte 200
StatusBetekenis
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 (binnenkort)
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).

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.

Parameters

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

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:knowledge_bases:read
  • Goedkeuring: none, geen extra stap.

Body

JSON, verplicht.

  • question string verplicht
    max. lengte 2000
  • top_k integer
    standaard: 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. standaard: "all"

Antwoorden

StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:register_links:delete
  • Goedkeuring: review, een tweede persoon of rol keurt goed.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • Verwijderen is zacht; zie Conventies.
  • dryRun query · string
    Validate the KB manage right and preview without writing. Een van: true, false
  • link_id path · string (uuid) verplicht
StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:register_links:read
  • Goedkeuring: none, geen extra stap.
  • link_id path · string (uuid) verplicht

JSON, verplicht.

  • filter object
    standaard: {}
  • sort object
  • sort.field string verplicht
    max. lengte 128
  • sort.direction string verplicht
    Een van: asc, desc
  • cursor string
    patroon ^\d{1,7}$
  • limit integer
    standaard: 50 · min. 1 · max. 200
  • aggregate object
  • aggregate.operation string verplicht
    Een van: count, sum, avg, min, max
  • aggregate.field string
    max. lengte 128
StatusBetekenis
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 (binnenkort)
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.

  • Stand: binnenkort, nog niet op productie.
  • Scope: prudai:register_links:write
  • Goedkeuring: confirm, de gebruiker bevestigt precies deze aanroep.
  • Dry run: ?dryRun=true laat zien wat er zou gebeuren en slaat niets op.
  • dryRun query · string
    Validate the KB manage right and preview without writing. Een van: true, false
  • link_id path · string (uuid) verplicht
StatusBetekenis
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 (binnenkort)
prudai leo register-links restore