io.enterpriseai.resources.KnowledgeClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/KnowledgeClient.java. Back to the Java SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class KnowledgeClient
Knowledge bases (RAG ingestion and ACL filtered retrieval).
Constructor KnowledgeClient
KnowledgeClient(Transport transport)
Creates the client on the shared transport; EnterpriseAIClient builds it and exposes it through the accessor of the same name.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
transport | Transport | yes | Transport shared by the sub-clients of one client. |
KnowledgeClient.addDocument
JsonNode addDocument(String id, Object body)
Add a document. Ingests a document (201). Needs the ReBAC relation editor and write access by the ACL (403 not_permitted_acl). Steps: 1. The content (content or content_base64, one is required, else 400) is scanned by ClamAV and YARA-X (422 file_blocked, 503 file_scan_unavailable), then the text is extracted by Docling (422 unsupported_media). 2. Personal data detection may raise the classification; a source_connector must be active. 3. A document with the same uri replaces the previous version (version + 1). 4. The text is chunked, embedded and stored; the poisoning screening may put the document in quarantine (status: quarantined). 409 knowledge_base_reindexing while a reindex runs; 409 embedding_dimension_mismatch; 503 vector_store_unavailable. Audited as knowledge.document.ingest.
Route: /v1/knowledge-bases/{kb_id}/documents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | Content, title, URI, classification, readers and metadata of the document. |
Returns: JsonNode. Decoded JSON answer of the operation "Add a document".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.addDocument
JsonNode addDocument(String id, Object body, RequestOptions options)
Add a document. Ingests a document (201). Needs the ReBAC relation editor and write access by the ACL (403 not_permitted_acl). Steps: 1. The content (content or content_base64, one is required, else 400) is scanned by ClamAV and YARA-X (422 file_blocked, 503 file_scan_unavailable), then the text is extracted by Docling (422 unsupported_media). 2. Personal data detection may raise the classification; a source_connector must be active. 3. A document with the same uri replaces the previous version (version + 1). 4. The text is chunked, embedded and stored; the poisoning screening may put the document in quarantine (status: quarantined). 409 knowledge_base_reindexing while a reindex runs; 409 embedding_dimension_mismatch; 503 vector_store_unavailable. Audited as knowledge.document.ingest.
Route: /v1/knowledge-bases/{kb_id}/documents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | Content, title, URI, classification, readers and metadata of the document. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Add a document".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.chunks
Page<JsonNode> chunks(String id, String docId, Map<String, ?> query)
List the chunks of a document. Chunks of the current version of a document in position order, paginated with cursor: chunk_id, ordinal, content (decrypted for sealed chunks), classification, sealed, active, generation, fts_config (text search configuration) and metadata (source_page, section_title, element_type, language, char_start, char_end, bbox, document_version, content_hash, embedding_model, token_count, structure with the table split marks). Only the chunks whose readers and classification the caller passes are listed. A quarantined or rejected document is shown only to tenant_admin, security_officer or data_steward (403 forbidden). Needs the ReBAC relation viewer; 404 not_found for a document the caller cannot read.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/chunks (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
docId | String | yes | Identifier (UUID) of the current document. | |
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
KnowledgeClient.create
JsonNode create(Object body)
Create a knowledge base. Creates a knowledge base with its embedding model (default: the platform RAG embedding model), which must be approved, have the embeddings capability and accept the classification. chunk_overlap must be lower than chunk_size (400 invalid_request); an unknown classification answers 400. A name already used in the tenant answers 409 conflict. Needs tenant_admin or developer; the caller becomes ReBAC owner. Audited as knowledge_base.create.
Route: /v1/knowledge-bases (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
body | Object | yes | Name, chunking, classification, ACL and embedding model of the knowledge base. |
Returns: JsonNode. Decoded JSON answer of the operation "Create a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.create
JsonNode create(Object body, RequestOptions options)
Create a knowledge base. Creates a knowledge base with its embedding model (default: the platform RAG embedding model), which must be approved, have the embeddings capability and accept the classification. chunk_overlap must be lower than chunk_size (400 invalid_request); an unknown classification answers 400. A name already used in the tenant answers 409 conflict. Needs tenant_admin or developer; the caller becomes ReBAC owner. Audited as knowledge_base.create.
Route: /v1/knowledge-bases (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
body | Object | yes | Name, chunking, classification, ACL and embedding model of the knowledge base. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Create a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.delete
void delete(String id)
Delete a knowledge base. Deletes the knowledge base, its documents and their vectors in the vector store. Needs the ReBAC relation owner, and the caller must be tenant_admin or its creator (403 forbidden). 404 not_found; 503 vector_store_unavailable. Audited as knowledge_base.delete.
Route: /v1/knowledge-bases/{kb_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. |
Returns: void.
Raises: the typed errors of the transport (Errors).
KnowledgeClient.deleteDocument
void deleteDocument(String id, String docId)
Delete a document. Deletes the document and its vectors. Needs the ReBAC relation editor and write access by the ACL: tenant_admin, an identity listed in writers, or, when writers is empty, developer or agent (else 403 not_permitted_acl). 404 not_found. Audited as knowledge.document.delete.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
docId | String | yes | Identifier (UUID) of the document. |
Returns: void.
Raises: the typed errors of the transport (Errors).
KnowledgeClient.diagnostics
JsonNode diagnostics(String id, Map<String, ?> query)
List the diagnostics of the queries. Recorded diagnostics of the queries on the knowledge base, newest first, diagnostics_id of an answer to select one: mode, effective strategy, stages (stage name, duration in milliseconds, candidates in and out), counts (filtered documents, dense and lexical candidates, fused, screened, deduplicated, dropped by the revalidation, final, context neighbours, cache hit) and results (rank, chunk, document, named scores). The query text is not stored, only its SHA-256. A caller sees its own queries; tenant_admin, security_officer, data_steward and auditor see every query. Needs the ReBAC relation viewer; 404 not_found for a caller outside the ACL or a diagnostics_id it cannot see.
Route: /v1/knowledge-bases/{kb_id}/query-diagnostics (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: JsonNode. Decoded JSON answer of the operation "List the diagnostics of the queries".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.documentStatus
JsonNode documentStatus(String kbId, String docId)
Read the status of a document. Status of one document version: document_id, document_key, version, version_state (current, superseded or deleted), document_status (uploaded, active, quarantined, rejected, failed...), searchable (true only for the current active version), chunks, extractor, and ingestion, the last ingestion job (job_id, state, attempts, last_error, updated_at) or null for a synchronous ingestion. Needs the ReBAC relation viewer; 404 not_found for a document the caller cannot read.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/status (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. | |
docId | String | yes | Identifier (UUID) of the document version, the document_id of the upload answer. |
Returns: JsonNode. Decoded JSON answer of the operation "Read the status of a document".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.documents
Page<JsonNode> documents(String id)
List the documents of a knowledge base. Documents the caller may read (one of its identities in the document readers, classification within its clearance), paginated with cursor. Needs the ReBAC relation viewer and read access to the knowledge base.
Route: /v1/knowledge-bases/{kb_id}/documents (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
KnowledgeClient.documents
Page<JsonNode> documents(String id, Map<String, ?> query)
List the documents of a knowledge base. Documents the caller may read (one of its identities in the document readers, classification within its clearance), paginated with cursor. Needs the ReBAC relation viewer and read access to the knowledge base.
Route: /v1/knowledge-bases/{kb_id}/documents (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
KnowledgeClient.get
JsonNode get(String id)
Get a knowledge base. Returns the knowledge base with its document count, its ingestion and retrieval pipeline, the running reindex job if any and the datasets the caller may see. Needs the ReBAC relation viewer and read access by the ACL; otherwise 404 not_found.
Route: /v1/knowledge-bases/{kb_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. |
Returns: JsonNode. Decoded JSON answer of the operation "Get a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.ingestionJob
JsonNode ingestionJob(String kbId, String jobId)
Read an ingestion job. An asynchronous ingestion job: job_id, kb_id, document_id, document_key, version, state (uploaded, quarantined, scanning, rejected, extracting, normalizing, chunking, embedding, indexing, enriching_memory, ready, partially_ready, failed, reindexing, deleting or deleted), attempts, lease_owner, lease_expires_at, next_attempt_at, last_error, title, file name, media type, detected_format, size_bytes, sha256, scan_id, extractor (the one that ran), storage (profile and quarantine or permanent location), creation, update and end, and history: every transition with from_state, to_state, at and detail (scan verdict, extractor, chunk count, retry with its backoff, OCR failure, memory skipped). Needs the ReBAC relation viewer; 404 not_found for a job of another knowledge base or a document the caller cannot read.
Route: /v1/knowledge-bases/{kb_id}/ingestion-jobs/{job_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. | |
jobId | String | yes | Identifier (UUID) of the ingestion job, the job_id of the upload answer. |
Returns: JsonNode. Decoded JSON answer of the operation "Read an ingestion job".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.list
Page<JsonNode> list()
List the knowledge bases. Knowledge bases of the tenant that the caller may read by their ACL, in name order, paginated with cursor.
Route: /v1/knowledge-bases (GET).
This element takes no parameter.
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
KnowledgeClient.list
Page<JsonNode> list(Map<String, ?> query)
List the knowledge bases. Knowledge bases of the tenant that the caller may read by their ACL, in name order, paginated with cursor.
Route: /v1/knowledge-bases (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
KnowledgeClient.quarantine
JsonNode quarantine(String kbId)
List the quarantined documents. Documents isolated by the poisoning screening (data steward review queue), oldest first, at most 200, each with the screening reasons in quarantine. Their chunks are not searchable. Needs tenant_admin, security_officer or data_steward and the ReBAC relation viewer.
Route: /v1/knowledge-bases/{kb_id}/quarantine (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. |
Returns: JsonNode. Decoded JSON answer of the operation "List the quarantined documents".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.query
JsonNode query(String id, Object body)
Query a knowledge base. Searches the knowledge base and returns results (chunk, score, injection risk, classification, provenance), citations and a lineage_run_id. Needs the ReBAC relation can_invoke. Steps: 1. The policy knowledge.query is evaluated and a quota reservation is taken. 2. The query is embedded with the model of the knowledge base; only chunks whose readers match the caller identities and whose classification fits its clearance are searched. 3. Retrieved chunks are screened for prompt injection (dropped in block mode) and checked against active sources. 4. hybrid re-scores the candidates with keyword overlap; rerank orders them with a rerank model (a refusal is reported in warnings, never hidden). A caller outside the ACL gets an empty result, audited as a denial. Audited as knowledge.query; usage is metered.
Route: /v1/knowledge-bases/{kb_id}/query (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | Query text and search options. |
Returns: JsonNode. Decoded JSON answer of the operation "Query a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.query
JsonNode query(String id, Object body, RequestOptions options)
Query a knowledge base. Searches the knowledge base and returns results (chunk, score, injection risk, classification, provenance), citations and a lineage_run_id. Needs the ReBAC relation can_invoke. Steps: 1. The policy knowledge.query is evaluated and a quota reservation is taken. 2. The query is embedded with the model of the knowledge base; only chunks whose readers match the caller identities and whose classification fits its clearance are searched. 3. Retrieved chunks are screened for prompt injection (dropped in block mode) and checked against active sources. 4. hybrid re-scores the candidates with keyword overlap; rerank orders them with a rerank model (a refusal is reported in warnings, never hidden). A caller outside the ACL gets an empty result, audited as a denial. Audited as knowledge.query; usage is metered.
Route: /v1/knowledge-bases/{kb_id}/query (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | Query text and search options. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Query a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.reindex
JsonNode reindex(String id, Object body)
Reindex with another embedding model. Queues the move of the knowledge base to another embedding model (worker job embeddings_reindex) and answers 202 with the job. The model must be approved, have the embeddings capability and accept the highest classification of the knowledge base and its documents (422 otherwise). The new vectors form a new generation; the two spaces are never mixed. Needs tenant_admin or developer, the ReBAC relation owner and write access. 409 knowledge_base_reindexing if a job is already running. Audited as knowledge_base.reindex.request.
Route: /v1/knowledge-bases/{kb_id}/reindex (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | Target embedding model and dimension. |
Returns: JsonNode. Decoded JSON answer of the operation "Reindex with another embedding model".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.reindex
JsonNode reindex(String id, Object body, RequestOptions options)
Reindex with another embedding model. Queues the move of the knowledge base to another embedding model (worker job embeddings_reindex) and answers 202 with the job. The model must be approved, have the embeddings capability and accept the highest classification of the knowledge base and its documents (422 otherwise). The new vectors form a new generation; the two spaces are never mixed. Needs tenant_admin or developer, the ReBAC relation owner and write access. 409 knowledge_base_reindexing if a job is already running. Audited as knowledge_base.reindex.request.
Route: /v1/knowledge-bases/{kb_id}/reindex (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | Target embedding model and dimension. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Reindex with another embedding model".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.reindexJobs
JsonNode reindexJobs(String id)
List the reindex jobs. Reindex jobs of the knowledge base: status, source and target model, dimensions and generation, progress in documents and chunks, attempts, error and dates. Needs the ReBAC relation viewer and read access.
Route: /v1/knowledge-bases/{kb_id}/reindex-jobs (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. |
Returns: JsonNode. Decoded JSON answer of the operation "List the reindex jobs".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.retryIngestion
JsonNode retryIngestion(String kbId, String jobId, String reason)
Retry a failed ingestion job. Puts a failed job back in the queue: to extracting when its scan already released the file (never scanned twice), else to quarantined; the attempts start again from zero. Any other state is refused with 409 ingestion_job_not_failed (a rejected file is never retried). Answers the job with its history. Audited knowledge.ingestion.retry. Needs the ReBAC relation editor.
Route: /v1/knowledge-bases/{kb_id}/ingestion-jobs/{job_id}/retry (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. | |
jobId | String | yes | Identifier (UUID) of the failed ingestion job. | |
reason | String | yes | Why the action is taken. Written to the audit trail with the actor and the time. |
Returns: JsonNode. Decoded JSON answer of the operation "Retry a failed ingestion job".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.reviewDocument
JsonNode reviewDocument(String kbId, String docId, Object body)
Review a quarantined document. Releases (chunks searchable again, status: active) or rejects (status: rejected) a quarantined document. Needs tenant_admin, security_officer or data_steward; the policy knowledge.document.review is evaluated. 409 document_not_quarantined; 404 not_found. The decision is recorded and audited as knowledge.document.release or knowledge.document.reject.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/review (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. | |
docId | String | yes | Identifier (UUID) of the document. | |
body | Object | yes | Decision and reason. |
Returns: JsonNode. Decoded JSON answer of the operation "Review a quarantined document".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.reviewDocument
JsonNode reviewDocument(String kbId, String docId, Object body, RequestOptions options)
Review a quarantined document. Releases (chunks searchable again, status: active) or rejects (status: rejected) a quarantined document. Needs tenant_admin, security_officer or data_steward; the policy knowledge.document.review is evaluated. 409 document_not_quarantined; 404 not_found. The decision is recorded and audited as knowledge.document.release or knowledge.document.reject.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/review (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. | |
docId | String | yes | Identifier (UUID) of the document. | |
body | Object | yes | Decision and reason. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Review a quarantined document".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.setAcl
JsonNode setAcl(String id, Object body)
Replace the ACL of a knowledge base. Replaces the readers and writers of the knowledge base. With apply_to_documents, the documents that inherit the knowledge base ACL (no readers of their own) and their chunks get the new readers; documents_updated gives their number. Needs the ReBAC relation owner, and the caller must be tenant_admin, security_officer or the creator. Audited as knowledge_base.acl.update; the retrieval cache is invalidated.
Route: /v1/knowledge-bases/{kb_id}/acl (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | The new ACL. |
Returns: JsonNode. Decoded JSON answer of the operation "Replace the ACL of a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.setAcl
JsonNode setAcl(String id, Object body, RequestOptions options)
Replace the ACL of a knowledge base. Replaces the readers and writers of the knowledge base. With apply_to_documents, the documents that inherit the knowledge base ACL (no readers of their own) and their chunks get the new readers; documents_updated gives their number. Needs the ReBAC relation owner, and the caller must be tenant_admin, security_officer or the creator. Audited as knowledge_base.acl.update; the retrieval cache is invalidated.
Route: /v1/knowledge-bases/{kb_id}/acl (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | The new ACL. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Replace the ACL of a knowledge base".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.setRetrieval
JsonNode setRetrieval(String id, Object body)
Set the retrieval strategy. Replaces the retrieval strategy of the knowledge base: default mode, fusion and its rrf_k, candidates per result, reranking and its model, deduplication, context window and token budget, conflict signal. A field left out takes its default; the options of a query override the strategy for that query. Needs the ReBAC relation owner and write access by the ACL (403 not_permitted_acl); 404 not_found for a caller outside the ACL. Audited as knowledge_base.retrieval.update; the retrieval cache is invalidated. Answers the knowledge base with its retrieval.
Route: /v1/knowledge-bases/{kb_id}/retrieval (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
body | Object | yes | The retrieval strategy. |
Returns: JsonNode. Decoded JSON answer of the operation "Set the retrieval strategy".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.uploadDocument
JsonNode uploadDocument(String kbId, byte[] content, String mimeType, Map<String, ?> fields, RequestOptions options)
Upload a document for asynchronous ingestion. Checks the size (413 payload_too_large, limit EAI_RAG_UPLOAD_MAX_BYTES), the declared mime_type against the real signature of the bytes (PDF, DOCX, XLSX and PPTX as ZIP packages with the right content types, PNG, JPEG, TIFF; text formats must be valid UTF-8 without NUL) and the extension of filename: 422 unsupported_format, format_mismatch, extension_mismatch or archive_refused (archive bomb, nested archive, too large once decompressed). The bytes are stored in the quarantine prefix of the documents storage profile (409 ingestion_storage_required without one, 503 ingestion_storage_unavailable), the document version is recorded with document_status uploaded and a durable job is created. Answers 202 with job_id, kb_id, document_id, document_key, version, state (uploaded), detected_format, size_bytes and sha256, and a Location header. The worker job knowledge_ingestion then scans the file through the file security domain (fail closed), extracts, chunks, embeds and indexes it. The same Idempotency-Key replays the same answer (header Idempotency-Replayed); with another body it is refused with 409 idempotency_conflict. Needs the ReBAC relation editor.
Route: /v1/knowledge-bases/{kb_id}/documents/uploads (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kbId | String | yes | Identifier (UUID) of the knowledge base. | |
content | byte[] | yes | Bytes of the file, sent base64 encoded as content_base64. | |
mimeType | String | yes | Declared media type, checked against the real signature of the bytes. | |
fields | Map<String, ?> | yes | Fields of the method (for example user and password), up to 16 text values. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Upload a document for asynchronous ingestion".
Raises: the typed errors of the transport (Errors).
KnowledgeClient.versions
JsonNode versions(String id, String docId)
List the versions of a document. Version history of a document, newest first: document_key (stable across versions) and items with document_id, version, state (current, superseded or deleted), searchable (only the current active version is searched), title, URI, media type, classification, content_hash, size, chunk count, extractor, language, collection, document_status, creation, superseded_by and superseded_at, deleted_at, and the Docling artifacts (kind, storage profile, object key, size, SHA-256). doc_id may be the current document or any past version. A version is listed only when the caller is among its readers and its classification fits the clearance. Needs the ReBAC relation viewer; 404 not_found otherwise.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/versions (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) of the knowledge base. | |
docId | String | yes | Identifier (UUID) of the document or of one of its past versions. |
Returns: JsonNode. Decoded JSON answer of the operation "List the versions of a document".
Raises: the typed errors of the transport (Errors).