resources/data.ts

Source: sdks/typescript/packages/sdk/src/resources/data.ts. Back to the TypeScript SDK reference index.

note

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 PrivacyResource

Privacy and data protection. Data protection services of the tenant: classification, DLP (data loss prevention), tokenization and envelope encryption.

Resource

PrivacyResource.classify

classify(body: { text?: string; media_id?: string } & Doc, opts?: CallOptions)

Classify a text or a media. With text, detects the entities with the tenant rules and returns classification, findings and engine, without changing the text. With media_id, returns the classification, findings and DLP result already computed for that media (404 not_found for an unknown media). One of the two is required (400 invalid_request). Open to any member of the tenant.

Route: /v1/privacy/classify (POST).

Name	Type	Default	Required	Description
body	{ text?: string; media_id?: string } & Doc		yes	Text or media to classify, and language.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PrivacyResource.detect

detect(body: { text: string } & Doc, opts?: CallOptions)

Inspect a text for sensitive data. Runs DLP on the text with the tenant rules, in mode detect unless mode says otherwise. The answer gives text, findings (type, position, score, classification, short preview, action, rule), action (strongest action applied), classification, mode, engine (builtin or presidio), blocked and count. An unknown mode answers 400. Open to any member of the tenant. Writes the audit event dlp.inspect (counts and types only).

Route: /v1/dlp/inspect (POST).

Name	Type	Default	Required	Description
body	{ text: string } & Doc		yes	Text, optional mode and language.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PrivacyResource.detokenize

detokenize(body: { tokens: string[]; purpose: string } & Doc, opts?: CallOptions)

Detokenize values. Returns the original values of tokens given in tokens or found in text.

Route: /v1/tokenization/detokenize (POST).

Name	Type	Default	Required	Description
body	{ tokens: string[]; purpose: string } & Doc		yes	Tokens or text holding tokens, and purpose.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PrivacyResource.encrypt

encrypt(body: { key: string; plaintext?: string; plaintext_base64?: string; aad?: string } & Doc, opts?: CallOptions)

Encrypt data with a tenant key. Encrypts plaintext (UTF-8 text) or plaintext_base64 (bytes) with the current version of the key, bound to aad. Returns ciphertext (eaienc1:...), key_id and key_version. One of the two inputs is required, and base64 must be valid (400 invalid_request); an unknown key answers 404 key_not_found. Open to any member of the tenant. Writes the audit event encryption.encrypt (size only).

Route: /v1/encryption/encrypt (POST).

Name	Type	Default	Required	Description
body	{ key: string; plaintext?: string; plaintext_base64?: string; aad?: string } & Doc		yes	Key, data to encrypt and associated data.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PrivacyResource.mask

mask(body: { text: string } & Doc, opts?: CallOptions)

Redact sensitive data from a text. Same as inspect, in mode mask by default: each finding is replaced by [TYPE] (for example [EMAIL]), or tokenized or blocked when a tenant rule or mode says so; a blocked text comes back empty with blocked: true. Open to any member of the tenant. Writes the audit event dlp.redact.

Route: /v1/dlp/redact (POST).

Name	Type	Default	Required	Description
body	{ text: string } & Doc		yes	Text, optional mode and language.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PrivacyResource.tokenize

tokenize(body: Doc, opts?: CallOptions)

Tokenize values. Replaces sensitive values by deterministic tokens tok_<type>_<hex> of the tenant (the same value always gives the same token), the values being stored encrypted in the vault. With values, returns tokens; with text, detects the entities and returns the tokenized text, findings and classification. One of the two is required (400 invalid_request). Open to any member of the tenant. Writes the audit event tokenization.tokenize (count only).

Route: /v1/tokenization/tokenize (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Values or text to tokenize.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Type alias DlpMode

DLP mode of DlpResource.redact: detect, mask, tokenize or block.

Definition: "detect" \| "mask" \| "tokenize" \| "block".

Class DlpResource

Privacy and data protection. Data protection services of the tenant: classification, DLP (data loss prevention), tokenization and envelope encryption.

Resource

DlpResource.createRule

createRule(body: Doc, opts?: CallOptions)

Create or update a DLP rule. Creates the rule, or replaces the rule of the same name. A rule needs an entity_type or a pattern (a valid regular expression); errors answer 400 invalid_request (unknown action, invalid pattern or classification). Needs tenant_admin or security_officer. Writes the audit event dlp.rule.upsert. Answers 201 with the rule.

Route: /v1/dlp/rules (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Name, entity type or pattern, action, classification and score of the rule.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DlpResource.inspect

inspect(body: { text: string } & Doc, opts?: CallOptions)

Inspect a text for sensitive data. Runs DLP on the text with the tenant rules, in mode detect unless mode says otherwise. The answer gives text, findings (type, position, score, classification, short preview, action, rule), action (strongest action applied), classification, mode, engine (builtin or presidio), blocked and count. An unknown mode answers 400. Open to any member of the tenant. Writes the audit event dlp.inspect (counts and types only).

Route: /v1/dlp/inspect (POST).

Name	Type	Default	Required	Description
body	{ text: string } & Doc		yes	Text, optional mode and language.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DlpResource.listRules

listRules(params?: ListParams, opts?: CallOptions)

List the DLP rules. Lists the DLP rules of the tenant ordered by name. Open to any member of the tenant. next_cursor is always null.

Route: /v1/dlp/rules (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

DlpResource.redact

redact(body: { text: string; mode?: DlpMode } & Doc, opts?: CallOptions)

Redact sensitive data from a text. Same as inspect, in mode mask by default: each finding is replaced by [TYPE] (for example [EMAIL]), or tokenized or blocked when a tenant rule or mode says so; a blocked text comes back empty with blocked: true. Open to any member of the tenant. Writes the audit event dlp.redact.

Route: /v1/dlp/redact (POST).

Name	Type	Default	Required	Description
body	{ text: string; mode?: DlpMode } & Doc		yes	Text, optional mode and language.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class TokenizationResource

Privacy and data protection. Data protection services of the tenant: classification, DLP (data loss prevention), tokenization and envelope encryption.

Resource

TokenizationResource.detokenize

detokenize(body: Doc, opts?: CallOptions)

Detokenize values. Returns the original values of tokens given in tokens or found in text.

Route: /v1/tokenization/detokenize (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Tokens or text holding tokens, and purpose.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

TokenizationResource.tokenize

tokenize(body: Doc, opts?: CallOptions)

Tokenize values. Replaces sensitive values by deterministic tokens tok_<type>_<hex> of the tenant (the same value always gives the same token), the values being stored encrypted in the vault. With values, returns tokens; with text, detects the entities and returns the tokenized text, findings and classification. One of the two is required (400 invalid_request). Open to any member of the tenant. Writes the audit event tokenization.tokenize (count only).

Route: /v1/tokenization/tokenize (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Values or text to tokenize.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class EncryptionResource

Privacy and data protection. Data protection services of the tenant: classification, DLP (data loss prevention), tokenization and envelope encryption.

Resource

EncryptionResource.createKey

createKey(body: { name: string; purpose?: string } & Doc, opts?: CallOptions)

Create an encryption key. Creates a named key with its first version; the data key is generated and wrapped by OpenBao Transit when configured, locally otherwise. The name must be lowercase letters, digits, ., _ or -, at most 63 characters (400 invalid_request); a name already used answers 409 conflict. Needs tenant_admin or security_officer. Writes the audit event encryption.key.create.

Route: /v1/encryption/keys (POST).

Name	Type	Default	Required	Description
body	{ name: string; purpose?: string } & Doc		yes	Name and purpose of the key.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EncryptionResource.decrypt

decrypt(body: { ciphertext: string; aad?: string; as_base64?: boolean } & Doc, opts?: CallOptions)

Decrypt a ciphertext. Decrypts an eaienc1 ciphertext of the tenant with the key version it names, checking the same aad as at encryption. Returns plaintext, or plaintext_base64 with as_base64 or when the data is not UTF-8 text, and key_version. Old versions keep decrypting after a rotation. Open to any member of the tenant. Writes the audit event encryption.decrypt.

Route: /v1/encryption/decrypt (POST).

Name	Type	Default	Required	Description
body	{ ciphertext: string; aad?: string; as_base64?: boolean } & Doc		yes	Ciphertext, associated data and output format.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EncryptionResource.encrypt

encrypt(body: { key: string; plaintext?: string; plaintext_base64?: string; aad?: string } & Doc, opts?: CallOptions)

Encrypt data with a tenant key. Encrypts plaintext (UTF-8 text) or plaintext_base64 (bytes) with the current version of the key, bound to aad. Returns ciphertext (eaienc1:...), key_id and key_version. One of the two inputs is required, and base64 must be valid (400 invalid_request); an unknown key answers 404 key_not_found. Open to any member of the tenant. Writes the audit event encryption.encrypt (size only).

Route: /v1/encryption/encrypt (POST).

Name	Type	Default	Required	Description
body	{ key: string; plaintext?: string; plaintext_base64?: string; aad?: string } & Doc		yes	Key, data to encrypt and associated data.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EncryptionResource.listKeys

listKeys(params?: ListParams, opts?: CallOptions)

List the encryption keys. Lists the encryption keys of the tenant ordered by name: id, name, backend (openbao-transit or local), purpose, current version and dates. Never the key material. Open to any member of the tenant.

Route: /v1/encryption/keys (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

EncryptionResource.rotateKey

rotateKey(id: string, opts?: CallOptions)

Rotate an encryption key. Adds a new version to the key: new encryptions use it, older ciphertexts keep decrypting with their own version. Needs tenant_admin or security_officer. Answers 404 key_not_found. Writes the audit event encryption.key.rotate.

Route: /v1/encryption/keys/{key_id}/rotate (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) or name of the key.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class KnowledgeBasesResource

Knowledge bases. Knowledge bases for retrieval augmented generation (RAG): documents are scanned, extracted, screened for personal data and poisoning, chunked, embedded through the Model Gateway and searched with ACL and clearance filters.

Resource

Attributes:

Name	Type	Required	Description
body	{ content?: string; content_base64?: string; mime_type?: string; title?: string; uri?: string; metadata?: Doc; readers?: string[]; classification?: string } & Doc,	yes	Document of addDocuments: content or base64 content, MIME type, title, URI, metadata, readers and classification.
id	string,	yes	Id of the knowledge base that receives the document in addDocuments.
opts	CallOptions) {	no	Per call options of addDocuments.

KnowledgeBasesResource.addDocuments

addDocuments(id: string, body: { content?: string; content_base64?: string; mime_type?: string; title?: string; uri?: string; metadata?: Doc; readers?: string[]; classification?: string } & Doc, opts?: CallOptions)

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	{ content?: string; content_base64?: string; mime_type?: string; title?: string; uri?: string; metadata?: Doc; readers?: string[]; classification?: string } & Doc		yes	Content, title, URI, classification, readers and metadata of the document.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.chunks

chunks(id: string, docId: string, params?: ListParams & { include_content?: boolean }, opts?: CallOptions)

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.
params	ListParams & { include_content?: boolean }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.cite

async cite(id: string, body: { query: string; top_k?: number; min_score?: number } & Doc, opts?: CallOptions)

Runs a query and keeps only the citations of authorized sources and the lineage run id.

Name	Type	Default	Required	Description
id	string		yes	Id of the knowledge base.
body	{ query: string; top_k?: number; min_score?: number } & Doc		yes	Request body, serialized as JSON.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

KnowledgeBasesResource.create

create(body: { name: string; description?: string; classification?: string; acl?: Doc; chunk_size?: number; chunk_overlap?: number; embedding_model?: string; dimensions?: number } & Doc, opts?: CallOptions)

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	{ name: string; description?: string; classification?: string; acl?: Doc; chunk_size?: number; chunk_overlap?: number; embedding_model?: string; dimensions?: number } & Doc		yes	Name, chunking, classification, ACL and embedding model of the knowledge base.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.delete

delete(id: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.deleteDocument

deleteDocument(id: string, docId: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.diagnostics

diagnostics(id: string, query?: { diagnostics_id?: string; limit?: number }, opts?: CallOptions)

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	{ diagnostics_id?: string; limit?: number }		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.documentStatus

documentStatus(kbId: string, docId: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.get

get(id: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.ingestionJob

ingestionJob(kbId: string, jobId: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.listDocuments

listDocuments(id: string, params?: ListParams, opts?: CallOptions)

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.
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.quarantine

quarantine(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the knowledge base.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.query

query(id: string, body: { query: string; top_k?: number; min_score?: number } & Doc, opts?: CallOptions)

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	{ query: string; top_k?: number; min_score?: number } & Doc		yes	Query text and search options.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.reindex

reindex(id: string, body: { embedding_model: string; dimensions?: number }, opts?: CallOptions)

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	{ embedding_model: string; dimensions?: number }		yes	Target embedding model and dimension.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.reindexJobs

reindexJobs(id: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.retrieve

async retrieve(id: string, body: { query: string; top_k?: number; min_score?: number } & Doc, opts?: CallOptions)

Runs a query and keeps only the ACL filtered results.

Name	Type	Default	Required	Description
id	string		yes	Id of the knowledge base.
body	{ query: string; top_k?: number; min_score?: number } & Doc		yes	Request body, serialized as JSON.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

KnowledgeBasesResource.retryIngestion

retryIngestion(kbId: string, jobId: string, body: { reason?: string } = {}, opts?: CallOptions)

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.
body	{ reason?: string }	{}	no	Optional reason of the retry.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.reviewDocument

reviewDocument(id: string, docId: string, body: { decision: "release" | "reject"; reason?: string }, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the knowledge base.
docId	string		yes	Identifier (UUID) of the document.
body	{ decision: "release" | "reject"; reason?: string }		yes	Decision and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.search

search(id: string, body: { query: string; top_k?: number; min_score?: number } & Doc, opts?: CallOptions)

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	{ query: string; top_k?: number; min_score?: number } & Doc		yes	Query text and search options.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.setAcl

setAcl(id: string, body: Doc, opts?: CallOptions)

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	Doc		yes	The new ACL.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.setRetrieval

setRetrieval(id: string, body: RetrievalStrategy, opts?: CallOptions)

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	RetrievalStrategy		yes	The retrieval strategy.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.uploadDocument

uploadDocument(kbId: string, body: DocumentUpload, opts?: CallOptions)

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.
body	DocumentUpload		yes	File bytes in base64, declared media type, file name, title, URI, classification, readers, metadata, collection and language.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

KnowledgeBasesResource.versions

versions(id: string, docId: string, opts?: CallOptions)

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.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface RetrievalStrategy

Body of setRetrieval: the retrieval strategy of a knowledge base; a field left out takes its default.

Doc

Fields:

Name	Type	Required	Description
mode	"vector" | "dense" | "lexical" | "hybrid"	no	Retrieval mode: vector, dense, lexical or hybrid.
fusion	"rrf" | "weighted"	no	Fusion of the hybrid mode: rrf (reciprocal rank fusion) or weighted.
rrf_k	number	no	Constant k of the reciprocal rank fusion (1 to 1000, default 60).
candidates	number	no	Candidate multiplier of each retriever before the fusion (1 to 20).
rerank	boolean	no	Orders the hits with a rerank model through the Model Gateway.
rerank_model	string	no	Registry id of the rerank model.
rerank_candidates	number	no	Number of hits given to the rerank model (1 to 200).
dedupe	boolean	no	Removes near duplicate chunks from the hits.
dedupe_threshold	number	no	Similarity above which two chunks are duplicates (0.5 to 1).
context_window	number	no	Context window in tokens, positive.
token_budget	number	no	Token budget of the context built from the hits (0 to 32000).
conflicts	boolean	no	Adds the heuristic signal signals.possible_conflicts to the answer.

Interface DocumentUpload

Body of uploadDocument: the file in base64 and its metadata, for the asynchronous ingestion.

Doc

Fields:

Name	Type	Required	Description
content_base64	string	yes	Content of the file, base64 encoded.
mime_type	string	yes	Media type of the content, for example application/pdf or image/png.
title	string	no	Title of the document.
filename	string	no	Original file name; its extension must match the real format.
uri	string	no	Source URI; the uri of an existing document makes this upload its next version.
classification	string	no	Classification of the document, never above the one of the knowledge base.
readers	string[]	no	Readers of the document (default: the readers of the knowledge base).
metadata	Doc	no	Free key-value pairs stored with the object and returned as they are; the platform never interprets them.
collection	string	no	Collection of the document, usable as a query filter.
language	string	no	Language of the user interface and of the messages: en or fr.

Interface MemoryWrite

Body of POST /v1/memory.

Doc

Fields:

Name	Type	Required	Description
memory_id	string	no	Existing item to update (new version). Omit it to create an item.
scope	MemoryContract["scope"]	no	What is backed up (clusters, services, data sets), as an object.
kind	MemoryContract["kind"]	no	Kind of memory: episodic, semantic, procedural, preference or fact.
content	string	no	Text of the memory.
content_ref	string	no	Reference to content stored elsewhere (not searchable).
classification	MemoryContract["classification"]	no	Classification of the memory content.
acl	MemoryContract["acl"]	no	Readers, writers and owners of the memory.
ttl_seconds	number | null	no	Lifetime in seconds. Once it has elapsed, the item expires and is no longer accepted.
subject_id	string	no	Data subject the memory is about, used by subject erasure.
source	Doc	no	Provenance of the memory.
deletable	boolean	no	When false, only tenant_admin can delete the item. Default true.
legal_hold	boolean	no	Put the memory under legal hold: it cannot be deleted, and an update cannot clear the hold. Default false.

Class MemoryResource

Memory. Memory Manager: long lived memory items of agents and users, following the Memory Contract v1, with ACL, lifetime, legal hold, versioning and hybrid search.

Resource

MemoryResource.addKnowledge

addKnowledge(agentId: string, body: { texts: string[]; scope?: string; team?: string; dataset_id?: string; classification?: string; retention_days?: number; legal_hold?: boolean; build_graph?: boolean }, opts?: CallOptions)

Ingest knowledge. Adds texts to the Cognee dataset of one scope (Cognee POST /api/v1/add, then POST /api/v1/cognify when build_graph), only when the policy enables knowledge_graph and the engine is cognee or hybrid (else 403 or 422 memory_capability_unsupported). Same DLP, classification, retention and isolation checks as a memory; relation editor on the agent. 201 with dataset, items and graph. Accepts an Idempotency-Key header. Audited as memory.knowledge.create without the content.

Route: /v1/memory/agents/{agent_id}/knowledge (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	{ texts: string[]; scope?: string; team?: string; dataset_id?: string; classification?: string; retention_days?: number; legal_hold?: boolean; build_graph?: boolean }		yes	Texts to ingest and their scope.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.agentPolicy

agentPolicy(agentId: string, opts?: CallOptions)

Read the memory policy of an agent. Engine choice (builtin, mem0, cognee, hybrid), instances, modes, scopes, memorization limits, retention, sharing and required isolation of the agent, with version, configured (false: defaults, builtin engine) and engines (per purpose memory or knowledge: instance, provider, isolation and capabilities). Relation viewer on the agent, or the agent itself.

Route: /v1/memory/agents/{agent_id}/policy (GET).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.agentPolicyVersions

agentPolicyVersions(agentId: string, opts?: CallOptions)

List the versions of the memory policy. Former versions of the memory policy of the agent, newest first (at most 200), each with its engine, instances, policy, author and date. Relation viewer on the agent.

Route: /v1/memory/agents/{agent_id}/policy/versions (GET).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.buildGraph

buildGraph(agentId: string, body: { dataset_ids?: string[] } = {}, opts?: CallOptions)

Build the knowledge graph. Runs Cognee POST /api/v1/cognify on readable datasets of the instance of the agent (all of them by default). Relation editor on the agent. Audited as memory.knowledge.build.

Route: /v1/memory/agents/{agent_id}/knowledge/graph (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	{ dataset_ids?: string[] }	{}	no	Datasets to process.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.datasets

datasets(agentId: string, params?: ListParams & { scope?: string }, opts?: CallOptions)

List the knowledge datasets. Datasets the caller may read through this agent, paginated with cursor.

Route: /v1/memory/agents/{agent_id}/knowledge/datasets (GET).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
params	ListParams & { scope?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.declareEngine

declareEngine(body: MemoryEngineDeclare, opts?: CallOptions)

Declare a memory engine instance. Declares an instance of Mem0 or Cognee installed and operated by the Navin Manager, for example one dedicated to a tenant (tenant_id: physical separation, as a bank requires). Only platform_admin (403 otherwise). The credential is a reference only (openbao://<path> or env://EAI_CRED_<NAME>), resolved server side. 409 conflict when the id exists or is reserved (builtin, mem0, cognee), 404 for an unknown tenant. Accepts an Idempotency-Key header. Audited as memory.engine.declare.

Route: /v1/memory/engines (POST).

Name	Type	Default	Required	Description
body	MemoryEngineDeclare		yes	The engine instance to declare.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.delete

delete(id: string, opts?: CallOptions)

Delete a memory item. Erases the content, the reference, the vector and the former versions of the item and marks it deleted. Allowed for a writer or owner of the item, or tenant_admin (else 403 not_permitted_acl). An item under legal hold answers 409 legal_hold (the refusal is audited); a non deletable item answers 409 conflict unless the caller is tenant_admin. 404 not_found. Audited as memory.delete.

Route: /v1/memory/{memory_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the memory item.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.deleteDataset

deleteDataset(agentId: string, datasetId: string, opts?: CallOptions)

Delete a knowledge dataset. Deletes the dataset in Cognee (DELETE /api/v1/datasets/{dataset_id}) and its index entries. 409 legal_hold when the dataset or one of its items is held. Audited as memory.knowledge.delete.

Route: /v1/memory/agents/{agent_id}/knowledge/datasets/{dataset_id} (DELETE).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
datasetId	string		yes	Identifier (UUID) of the Navin index entry of the dataset.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.deleteEngine

deleteEngine(engineId: string, opts?: CallOptions)

Remove a declared memory engine instance. Removes a declared instance and the tenant credentials bound to it. Only platform_admin. 409 memory_engine_in_use while an agent policy or a memory still uses it; 404 memory_engine_not_found. Audited as memory.engine.delete.

Route: /v1/memory/engines/{engine_id} (DELETE).

Name	Type	Default	Required	Description
engineId	string		yes	Identifier of the engine instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.deleteEngineCredential

deleteEngineCredential(engineId: string, opts?: CallOptions)

Unbind the credential of the tenant. Removes the credential of this tenant on the instance; the credential of the instance is used again. Role tenant_admin. Audited as memory.engine.change.

Route: /v1/memory/engines/{engine_id}/credential (DELETE).

Name	Type	Default	Required	Description
engineId	string		yes	Identifier of the engine instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.engineCapabilities

engineCapabilities(engineId: string, opts?: CallOptions)

Read the capabilities of a memory engine. Declarative capability set of the engine: only what its provider really executes. memory: among remember, recall, search, update, forget, list, get, purge, get_health, get_capabilities; knowledge: among ingest_knowledge, build_graph, search_graph, get_relations, delete_dataset. An operation outside this set answers 422 memory_capability_unsupported. Also gives isolation for the tenant and session_memory (true for builtin only: session memory never goes to an external engine). Nothing is sent to the engine.

Route: /v1/memory/engines/{engine_id}/capabilities (GET).

Name	Type	Default	Required	Description
engineId	string		yes	Identifier of the engine instance (builtin, mem0, cognee or a declared id).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.engineHealth

engineHealth(engineId: string, opts?: CallOptions)

Check the health of a memory engine. Calls the engine with the credential of the tenant: Mem0 GET /auth/setup-status then GET /configure/providers, Cognee GET /health then GET /api/v1/datasets. Answers status up (or degraded), or down with error and reason (never a secret). Roles tenant_admin, developer, security_officer or auditor.

Route: /v1/memory/engines/{engine_id}/health (GET).

Name	Type	Default	Required	Description
engineId	string		yes	Identifier of the engine instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.engines

engines(opts?: CallOptions)

List the memory engines. Memory engines the tenant may use (Navin Memory Provider): builtin (the Memory Manager store), the platform instances mem0 and cognee rendered by the Navin Manager from its bindings (only when configured), and the instances declared by the platform administrator (shared ones and those dedicated to this tenant; a dedicated instance of another tenant is never listed). Each entry gives provider, base_url, origin (builtin, manager_binding, declared), dedicated, credential_bound (the credential itself is never returned), isolation (logical, backend or dedicated_instance: the separation this instance guarantees for the tenant) and capabilities. Navin Enterprise never installs nor configures an engine: the Navin Manager does.

Route: /v1/memory/engines (GET).

Name	Type	Default	Required	Description
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.export

export(agentId: string, body: { scopes?: string[] } = {}, opts?: CallOptions)

Export the memories of an agent. Exports at most 1000 readable memories with their content (untrusted data). Refused to agents (403). Audited as memory.export without the content.

Route: /v1/memory/agents/{agent_id}/memories/export (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	{ scopes?: string[] }	{}	no	Scopes to export (default: every readable scope).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.forget

forget(agentId: string, itemId: string, opts?: CallOptions)

Forget a memory of an agent. Deletes the memory in its engine (Mem0 DELETE /memories/{memory_id}, Cognee data item deletion, builtin soft delete) and marks the index entry deleted. 409 legal_hold; only the owner agent of a shared memory (403). Audited as memory.provider.delete.

Route: /v1/memory/agents/{agent_id}/memories/{item_id} (DELETE).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
itemId	string		yes	Identifier (UUID) of the Navin index entry.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.get

get(id: string, opts?: CallOptions)

Get a memory item. Returns the item as a Memory Contract document with its history (former version numbers and dates). An expired item, or one the caller may not read by ACL or clearance, answers 404 not_found.

Route: /v1/memory/{memory_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the memory item.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.list

list(params?: ListParams, opts?: CallOptions)

List the memory items. Items the caller may read (listed in readers, classification within its clearance, not expired, not deleted), as Memory Contract documents, paginated with cursor.

Route: /v1/memory (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.memories

memories(agentId: string, params?: ListParams & { scope?: string; include_content?: boolean }, opts?: CallOptions)

List the memories of an agent. Index entries of the memories the caller may read through this agent (readable scopes of the policy, classification within the clearance, not expired), paginated with cursor. With include_content=true (at most 100 per page) the content is read from the engine and returned as untrusted data. Audited as memory.provider.read.

Route: /v1/memory/agents/{agent_id}/memories (GET).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
params	ListParams & { scope?: string; include_content?: boolean }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.memoryItem

memoryItem(agentId: string, itemId: string, opts?: CallOptions)

Get a memory of an agent. Index entry and content (read from the engine, untrusted data) of one memory. An item of a scope the caller may not read answers 404, never 403, so its existence is not disclosed. Audited as memory.provider.read.

Route: /v1/memory/agents/{agent_id}/memories/{item_id} (GET).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
itemId	string		yes	Identifier (UUID) of the Navin index entry.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.purge

purge(agentId: string, body: { scope: string; confirm: boolean; team?: string; session_id?: string }, opts?: CallOptions)

Purge one scope of an agent. Deletes every memory and dataset of one scope of the caller (Mem0 DELETE /memories with the identifiers of the scope, Cognee dataset deletion, builtin soft delete). confirm must be true (400). 409 legal_hold when an item of the scope is held. Audited as memory.provider.purge.

Route: /v1/memory/agents/{agent_id}/memories/purge (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	{ scope: string; confirm: boolean; team?: string; session_id?: string }		yes	The scope to purge and the confirmation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.recall

recall(agentId: string, body: AgentMemoryRecall, opts?: CallOptions)

Recall memories for the LLM. Searches the readable scopes on the engines of the policy (hybrid: Mem0 and Cognee, merged and deduplicated by content, every source kept in sources), keeps only the results indexed by Navin for a readable scope and within the clearance (permission check before anything reaches the LLM), screens them for prompt injection (blocked items dropped) and returns them as untrusted data: framed_content wrapped in the untrusted markers and context_segments of type memory for the Context Manager, never instructions. The policy decision memory.search is evaluated. Audited as memory.provider.read with counts only.

Route: /v1/memory/agents/{agent_id}/recall (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	AgentMemoryRecall		yes	Query, scopes, number of results and session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.relations

relations(agentId: string, datasetId: string, opts?: CallOptions)

Read the relations of a dataset. Nodes and edges of the knowledge graph of one readable dataset (Cognee GET /api/v1/datasets/{dataset_id}/graph), screened for prompt injection and returned as untrusted data. 404 for a dataset the caller may not read. Audited as memory.provider.read.

Route: /v1/memory/agents/{agent_id}/knowledge/datasets/{dataset_id}/relations (GET).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
datasetId	string		yes	Identifier (UUID) of the Navin index entry of the dataset.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.remember

remember(agentId: string, body: AgentMemoryWrite, opts?: CallOptions)

Remember through the engine of the agent. Writes one memory through the engine of the agent policy (session scope: always the builtin store; hybrid: Mem0). 201 with items (index entries, without content), engine and engine_instance. The context (tenant, organization, project, user, agent, session) is derived server side from the authenticated principal, the agent registry and the verified session, never from the body. Checks, each refusal audited: an agent only uses its own memory (403 memory_agent_mismatch), the scope and the kind must be allowed by the policy (403), shared scopes need editor on the agent, the engine must announce remember (422 memory_capability_unsupported) and guarantee the required isolation (409), secrets, passwords, tokens and keys are refused (422 memory_secret_refused), personal data when the policy forbids it (422), a classification above the policy or the clearance (403), a retention above the policy (422). Accepts an Idempotency-Key header. Audited as memory.provider.create without the content.

Route: /v1/memory/agents/{agent_id}/memories (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	AgentMemoryWrite		yes	The memory to remember.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.restoreAgentPolicy

restoreAgentPolicy(agentId: string, version: number, opts?: CallOptions)

Restore a version of the memory policy. Applies a former version again as a new version, with the same checks as PUT .../policy. 404 for an unknown version. Audited as memory.policy.restore.

Route: /v1/memory/agents/{agent_id}/policy/restore (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
version	number		yes	Version number (1 or more).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.search

search(body: { query: string; scope?: Doc; top_k?: number } & Doc, opts?: CallOptions)

Search the memory. Scores the visible items (at most the 2000 most recently updated ones with content) and returns the best top_k with score, keyword_score and vector_score. keyword: share of query terms found; vector: cosine similarity with the query embedding (only items embedded with the current model); hybrid (default): half of each. Recalled content is screened for prompt injection; blocked items are dropped. The policy memory.search is evaluated. 400 invalid_request for an unknown mode. Audited as memory.search.

Route: /v1/memory/search (POST).

Name	Type	Default	Required	Description
body	{ query: string; scope?: Doc; top_k?: number } & Doc		yes	Query, optional scope and kind, number of results and mode.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.searchKnowledge

searchKnowledge(agentId: string, body: { query: string; dataset_ids?: string[]; top_k?: number; search_type?: "CHUNKS" | "CHUNKS_LEXICAL" | "SUMMARIES" | "RAG_COMPLETION" | "GRAPH_COMPLETION" }, opts?: CallOptions)

Search the knowledge graph. Cognee POST /api/v1/search, one readable dataset per call so every passage is attributed to its dataset; results are screened and returned as untrusted data with framed_content. The policy decision memory.search is evaluated. Audited as memory.provider.read.

Route: /v1/memory/agents/{agent_id}/knowledge/search (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	{ query: string; dataset_ids?: string[]; top_k?: number; search_type?: "CHUNKS" | "CHUNKS_LEXICAL" | "SUMMARIES" | "RAG_COMPLETION" | "GRAPH_COMPLETION" }		yes	Query, datasets, number of results and search type.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.searchMemories

searchMemories(agentId: string, body: AgentMemoryRecall, opts?: CallOptions)

Search the memories of an agent. Same search as recall for a person who consults the memories (no context_segments); shared scopes need editor on the agent. Results are untrusted data. Audited as memory.provider.read.

Route: /v1/memory/agents/{agent_id}/memories/search (POST).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	AgentMemoryRecall		yes	Query, scopes, number of results and session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.setAgentPolicy

setAgentPolicy(agentId: string, body: { engine?: "builtin" | "mem0" | "cognee" | "hybrid"; mem0_instance?: string; cognee_instance?: string; policy?: Doc }, opts?: CallOptions)

Set the memory policy of an agent. Replaces the memory policy of the agent (new version, the former one is kept for a restore). Checks: roles tenant_admin, developer or application_owner and relation editor on the agent (403); global_access needs tenant_admin; default_scope must be a write scope and shared_with existing agents (400); the chosen instances must exist, match the provider and guarantee required_isolation (409 memory_isolation_unsatisfied: a dedicated instance installed by the Navin Manager is required). The policy decision memory.policy.update is enforced. shared_with writes or deletes the OpenFGA relation memory_reader of each agent on this one. Audited as memory.policy.update, plus memory.engine.change when the engine or an instance changes and memory.share when the sharing changes.

Route: /v1/memory/agents/{agent_id}/policy (PUT).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
body	{ engine?: "builtin" | "mem0" | "cognee" | "hybrid"; mem0_instance?: string; cognee_instance?: string; policy?: Doc }		yes	Engine choice, instances and memory policy of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.setEngineCredential

setEngineCredential(engineId: string, credentialRef: string, opts?: CallOptions)

Bind the credential of the tenant on an engine. Binds the credential of this tenant on a shared instance (openbao://<path> reference to a secret of the tenant). On a Cognee instance with backend access control, it is the API key of the Cognee user of the tenant: its datasets and permissions are then enforced by Cognee itself (isolation becomes backend). On Mem0 a key does not separate the memories (logical stays). Role tenant_admin. Audited as memory.engine.change.

Route: /v1/memory/engines/{engine_id}/credential (PUT).

Name	Type	Default	Required	Description
engineId	string		yes	Identifier of the engine instance.
credentialRef	string		yes	Reference openbao://<path> to a secret of the tenant.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.updateMemory

updateMemory(agentId: string, itemId: string, content: string, opts?: CallOptions)

Update a memory of an agent. Replaces the content of a memory in its engine (Mem0 PUT /memories/{memory_id}, builtin new version) after the same DLP checks as a creation; the version increases. Only the owner agent of a shared memory may change it (403); a held item answers 409 legal_hold. Audited as memory.provider.update.

Route: /v1/memory/agents/{agent_id}/memories/{item_id} (PATCH).

Name	Type	Default	Required	Description
agentId	string		yes	Name or identifier of the agent.
itemId	string		yes	Identifier (UUID) of the Navin index entry.
content	string		yes	Text (1 to 20000 characters); secrets are refused.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

MemoryResource.write

write(body: MemoryWrite, opts?: CallOptions)

Write a memory item. Creates an item, or a new version of memory_id (201, Memory Contract document). Steps: 1. kind and scope.type are checked (400 invalid_request); content or content_ref is required. 2. Personal data detection may raise the classification; a classification above the caller clearance answers 403 policy_denied; the policy memory.write is evaluated. 3. For an update, the caller must be a writer or owner (403 not_permitted_acl) before the content is sent to the embedding model. 4. The content is embedded and stored. A new item defaults to the caller as reader, writer and owner, and to the user scope of the caller. Audited as memory.create or memory.update.

Route: /v1/memory (POST).

Name	Type	Default	Required	Description
body	MemoryWrite		yes	The memory item to write.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface RagAgentInstanceCreate

Body of ragAgent.create: the activation record of a RAG Agent instance, created in draft.

Doc

Fields:

Name	Type	Required	Description
name	string	yes	Display name of the instance.
project	string	yes	Identifier of the project the results are restricted to.
deployment_model	"shared" | "dedicated"	yes	shared (the existing shared runtime) or dedicated (a runtime installed by the Navin Manager).
generation_model	string	yes
embedding_model	string	yes	Registry id of the embedding model of the instance.
id	string	no	LiteLLM model_name, unique in the profile.
description	string	no	Free description of the instance.
organization_id	string	no	Organization of the tenant the instance belongs to.
business_unit_id	string	no	Business unit the instance belongs to.
version	string	no	RAG Agent version to deploy (default: the current one).

Class RagAgentResource

Navin Enterprise RAG Agent instances: activation and lifecycle owned by the Control Plane.

Resource

RagAgentResource.backup

backup(instanceId: string, opts?: CallOptions)

Back up an instance (not supported). Answers 501 rag_agent_backup_not_supported with parts and the reason of each one: the RAG runtime has no admin route to export the rag schema rows of an instance, the knowledge domain has no export of a knowledge base. Nothing is pretended; the refusal is audited.

Route: /v1/rag-agent/instances/{instance_id}/backup (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.create

create(body: RagAgentInstanceCreate, opts?: CallOptions)

Create a draft RAG Agent instance. Creates the activation record in draft (201) with its immutable id (given, for example the id chosen by the RAG runtime, or generated). Needs a tenant administrator or an owner of the project (403 forbidden); unknown project: 404 rag_agent_project_not_found; a name or an id already used: 409 conflict. With Idempotency-Key a retry replays the first answer. Audited as rag_agent.create.

Route: /v1/rag-agent/instances (POST).

Name	Type	Default	Required	Description
body	RagAgentInstanceCreate		yes	Name, project, organization and business unit, deployment model, generation and embedding models of the registry, optional version.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.delete

delete(instanceId: string, opts?: CallOptions)

Delete an instance. Long operation (202, status deleting then deleted) from draft, stopped or failed (a ready instance is stopped first, else 409). Removes only what the instance owns, as recorded in resources: its knowledge base and its Qdrant points, the objects under its storage prefix, its agent memories and memory policy, its tuples, API key and secret, its agent; the governed application is retired. The shared runtime, a shared database, the Qdrant collection shared by the tenant knowledge bases and the storage profile are kept. Each step lists deleted and kept. Audited as rag_agent.delete and rag_agent.delete.completed.

Route: /v1/rag-agent/instances/{instance_id} (DELETE).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.deleteLogo

deleteLogo(instanceId: string, opts?: CallOptions)

Remove the logo of an instance. Back to the default logo of the runtime: the branding no longer points to an object, version is incremented and the stored object is removed. Without a logo, answers the branding unchanged. Same rights as the PUT; audited as rag_agent.branding.logo.remove.

Route: /v1/rag-agent/instances/{instance_id}/branding/logo (DELETE).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.get

get(instanceId: string, opts?: CallOptions)

Read a RAG Agent instance. The activation record with serving (true for ready and degraded), the current operation and run, validation, last_error and the steps of the current run in order (state, attempts, detail, logs, times). This is the route the RAG runtime reads at startup and on demand.

Route: /v1/rag-agent/instances/{instance_id} (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance, the same in the Control Plane and in the RAG runtime.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.getBranding

getBranding(instanceId: string, opts?: CallOptions)

Read the branding of an instance. The branding chosen in the activation journey, owned by the Control Plane: agent_name, sidebar_color, navbar_color, the text colours computed for them (sidebar_text_color, navbar_text_color, black or white, contrast 4.5:1 or more), logo (content_type, sha256, size_bytes, url) or null, version, updated_at, and app_url (the URL of the web application once known). A null field means the default of the runtime. The RAG runtime keeps a replica of it for its public login page and rewrites it when version is newer. Any principal of the tenant; another tenant's instance answers 404.

Route: /v1/rag-agent/instances/{instance_id}/branding (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.getLogo

getLogo(instanceId: string, opts?: CallOptions)

Read the logo of an instance. The logo bytes, read from the storage domain and checked against the recorded sha256, with the Content-Type of the validated format (image/png or image/jpeg), X-Content-Type-Options: nosniff, a Content-Security-Policy starting with default-src 'none' and an ETag. 404 rag_agent_logo_not_found when the instance has no logo. Any principal of the tenant.

Route: /v1/rag-agent/instances/{instance_id}/branding/logo (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.health

health(instanceId: string, opts?: CallOptions)

Health of an instance. Real checks: readiness URL of the runtime (GET /readyz), knowledge base (row, vector store qdrant, Qdrant /readyz) and model gateway (generation and embedding models in the registry, usable). status is up, degraded or down (runtime down); instance_status is the lifecycle status. Each check has status, duration_ms and reason when not up.

Route: /v1/rag-agent/instances/{instance_id}/health (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.list

list(query?: { status?: string; project?: string; limit?: number }, opts?: CallOptions)

List the RAG Agent instances. Activation records of the tenant, newest first, with status, deployment model, versions and owned resources (one page, next_cursor null). Filters: status, project.

Route: /v1/rag-agent/instances (GET).

Name	Type	Default	Required	Description
query	{ status?: string; project?: string; limit?: number }		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.provision

provision(instanceId: string, opts?: CallOptions)

Provision an instance. Long operation (202, Operation-Id): status provisioning then starting, steps from validation to activation run by the worker. From a validated draft (else 409 rag_agent_not_validated) or after a failed provisioning, which resumes from the failed step. Repeated while provisioning or once ready: changed: false. Audited as rag_agent.provision, each step as rag_agent.step.

Route: /v1/rag-agent/instances/{instance_id}/provision (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.restart

restart(instanceId: string, opts?: CallOptions)

Restart an instance. Long operation (202): from ready, degraded, stopped or after a failed restart, steps deployment (Navin Manager restart for a dedicated instance), health, smoke, activation. A restart in progress: changed: false.

Route: /v1/rag-agent/instances/{instance_id}/restart (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.restore

restore(instanceId: string, backupId: string, opts?: CallOptions)

Restore an instance (not supported). Answers 501 rag_agent_backup_not_supported with the same parts as the backup: no backup of an instance can be made for real yet. Audited.

Route: /v1/rag-agent/instances/{instance_id}/restore (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
backupId	string		yes	Identifier of the backup to restore.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.start

start(instanceId: string, opts?: CallOptions)

Start an instance. Long operation (202): from stopped (or after a failed start or stop), steps deployment (Navin Manager start for a dedicated instance, status only for a shared one), health, smoke, activation (governed application active). Already starting or ready: changed: false.

Route: /v1/rag-agent/instances/{instance_id}/start (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.stop

stop(instanceId: string, opts?: CallOptions)

Stop an instance. Long operation (202): from ready, degraded or after a failed start, restart, upgrade or stop, steps deployment (Navin Manager stop for a dedicated instance, status only for a shared one) and activation (governed application suspended, reason rag_instance_stopped); status stopped. Already stopping or stopped: changed: false.

Route: /v1/rag-agent/instances/{instance_id}/stop (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.updateBranding

updateBranding(instanceId: string, body: RagAgentBrandingUpdate, opts?: CallOptions)

Change the branding of an instance. Writes the fields given (an absent field is kept, null brings it back to the default of the runtime) and answers the branding. Colours are #RRGGBB (stored in upper case); the text drawn on them is black or white, whichever contrasts most (WCAG 2.2 relative luminance, the rule of the RAG frontend), and a colour whose text would stay under 4.5:1 answers 422 rag_agent_branding_contrast. app_url must be an https URL without credentials (422 rag_agent_app_url_invalid). A change of the name, the colours or the logo increments version; expected_version different from the current one answers 409 rag_agent_branding_version_conflict. With an Idempotency-Key, a retry with the same body replays the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Needs a tenant administrator or an owner of the project (403 forbidden); refused while the instance is deleting or deleted (409). Audited as rag_agent.branding.update.

Route: /v1/rag-agent/instances/{instance_id}/branding (PUT).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
body	RagAgentBrandingUpdate		yes	The branding fields to write.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.upgrade

upgrade(instanceId: string, version: string, opts?: CallOptions)

Upgrade an instance. Long operation (202), status updating: a shared instance follows the shared runtime, so the deployment step checks that the runtime runs the requested version (else shared_runtime_version_mismatch); a dedicated one is reinstalled by the Navin Manager. Then health, smoke, activation; deployed_version becomes the version. The same version already deployed or in progress: changed: false.

Route: /v1/rag-agent/instances/{instance_id}/upgrade (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
version	string		yes	Version to deploy (letters, digits, ., _, +, -, up to 64 characters).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.uploadLogo

uploadLogo(instanceId: string, input: RagAgentLogoUpload | FormData, opts?: CallOptions)

Upload the logo of an instance. Multipart file (with the optional text fields filename and mime_type). PNG or JPEG only: SVG and any other format are refused. The real signature, the declared Content-Type and the file extension must match; 32 to 1024 pixels a side, 512 KiB at most; else 422 rag_agent_logo_invalid with details.reason (format_not_allowed, signature_invalid, signature_mismatch, extension_mismatch, dimensions_out_of_bounds, too_large, empty). The file is then scanned by the file security domain, fail closed: a blocked file answers 422 file_blocked, a scanner down 503 file_scan_unavailable. It is stored through the storage domain in the documents storage profile of the tenant under rag-agent/<tenant>/<instance>/branding/ (409 rag_agent_branding_storage_required without such a profile, 503 rag_agent_branding_storage_unavailable when it cannot be reached); the replaced object is removed. Increments version and answers the branding. Same rights as the PUT; audited as rag_agent.branding.logo.update (a refusal is audited as a denial).

Route: /v1/rag-agent/instances/{instance_id}/branding/logo (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
input	RagAgentLogoUpload | FormData		yes	Logo to upload, or a ready FormData carrying the part file.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RagAgentResource.validate

validate(instanceId: string, opts?: CallOptions)

Validate an instance. Real checks before provisioning: the project exists and the caller may administer it, the generation model exists in the registry with the chat capability and a usable status, the embedding model resolves in the Model Gateway (capability embeddings), the quota of instances, Qdrant answers, the shared runtime answers (shared model) or the Navin Manager answers (dedicated model, an unpublished catalog service is a warning). From draft or after a failed validation. 200 with validation and status draft; 422 rag_agent_validation_failed with the failed checks (status failed, step validation). Audited as rag_agent.validate and rag_agent.validate.completed.

Route: /v1/rag-agent/instances/{instance_id}/validate (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface RagAgentBranding

Branding of a RAG Agent instance, owned by the Control Plane: name, colours, logo summary, version and app URL.

Doc

Fields:

Name	Type	Required	Description
agent_name	string | null	no	Name of the agent shown to the users, 1 to 80 characters, without <, > nor control characters.
sidebar_color	string | null	no	Colour of the sidebar, #RRGGBB; the text on it is black or white with a contrast of 4.5:1 or more.
navbar_color	string | null	no	Colour of the top bar, #RRGGBB; the text on it is black or white with a contrast of 4.5:1 or more.
sidebar_text_color	string | null	no	Text colour of the sidebar, black or white, chosen for a contrast of 4.5:1 or more.
navbar_text_color	string | null	no	Text colour of the navigation bar, black or white, chosen for a contrast of 4.5:1 or more.
logo	{ content_type: string; sha256: string; size_bytes: number; url: string } | null	no	Custom logo (content type, sha256, size in bytes, URL), or null for the default logo.
version	number	no	Version of the branding, increased by every write; the RAG runtime replica follows a newer version.
updated_at	string | null	no	Time of the last write of the branding.
app_url	string | null	no	URL of the web application of the instance once known, https only, without credentials (up to 2048 characters).

Interface RagAgentBrandingUpdate

Body of ragAgent.updateBranding: the keys given are written, null brings a field back to the default.

Fields:

Name	Type	Required	Description
agent_name	string | null	no	Name of the agent shown to the users, 1 to 80 characters, without <, > nor control characters.
sidebar_color	string | null	no	Colour of the sidebar, #RRGGBB; the text on it is black or white with a contrast of 4.5:1 or more.
navbar_color	string | null	no	Colour of the top bar, #RRGGBB; the text on it is black or white with a contrast of 4.5:1 or more.
app_url	string | null	no	URL of the web application of the instance once known, https only, without credentials (up to 2048 characters).
expected_version	number	no	Version the caller last read. The change is refused with 409 when the object changed since (optimistic concurrency).

Interface RagAgentLogoUpload

Logo of ragAgent.uploadLogo: PNG or JPEG, 32 to 1024 pixels, 512 KiB at most.

Fields:

Name	Type	Required	Description
file	Blob | Uint8Array	yes	Bytes of the image, as a Blob or a Uint8Array.
filename	string	yes	Name of the logo file; its extension must match the real format.
mime_type	"image/png" | "image/jpeg"	yes	Media type of the content, for example application/pdf or image/png.

Interface ComplianceInstanceCreate

Body of POST /v1/compliance/instances (ADR-0177 section 8).

Doc

Fields:

Name	Type	Required	Description
name	string	yes
project	string	yes	Identifier of the project the results are restricted to.
deployment_model	"shared" | "dedicated"	yes	shared (the existing shared runtime) or dedicated (a runtime installed by the Navin Manager).
generation_model	string	yes
embedding_model	string	yes
sector	"generic" | "banking" | "insurance" | "industry"	no	generic (default), banking, insurance or industry.
pack	"banking" | "insurance" | "industry" | null	no	Sector pack loaded on top of the generic core; null for the core alone.
id	string	no	LiteLLM model_name, unique in the profile.
description	string	no
organization_id	string	no
business_unit_id	string	no
version	string	no

Class ComplianceResource

Navin Enterprise Compliance & Audit Agent instances: activation and lifecycle owned by the Control Plane, the same model as the RAG Agent instances (ADR-0177 section 8).

Resource

ComplianceResource.backup

backup(instanceId: string, opts?: CallOptions)

Back up an instance (not supported). Answers 501 compliance_backup_not_supported with parts and the reason of each one: the compliance runtime has no admin route to export the compliance schema rows of an instance, the knowledge domain has no export of a knowledge base. Nothing is pretended; the refusal is audited.

Route: /v1/compliance/instances/{instance_id}/backup (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.create

create(body: ComplianceInstanceCreate, opts?: CallOptions)

Create a draft Compliance & Audit Agent instance. Creates the activation record in draft (201) with its immutable id (given, for example the id chosen by the compliance runtime, or generated), its sector and its pack. Needs a tenant administrator or an owner of the project (403 forbidden); unknown project: 404 compliance_project_not_found; a name or an id already used: 409 conflict. With Idempotency-Key a retry replays the first answer. Audited as compliance.create.

Route: /v1/compliance/instances (POST).

Name	Type	Default	Required	Description
body	ComplianceInstanceCreate		yes	Name, project, organization and business unit, sector and pack, deployment model, generation and embedding models of the registry, optional version.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.delete

delete(instanceId: string, opts?: CallOptions)

Delete an instance. Long operation (202, status deleting then deleted) from draft, stopped or failed (a ready instance is stopped first, else 409). Removes only what the instance owns, as recorded in resources: its knowledge base and its Qdrant points, the objects under its storage prefix, its agent memories and memory policy, its tuples, API key and secret, its agent; the governed application is retired. The shared runtime, a shared database, the Qdrant collection shared by the tenant knowledge bases and the storage profile are kept. Each step lists deleted and kept. Audited as compliance.delete and compliance.delete.completed.

Route: /v1/compliance/instances/{instance_id} (DELETE).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.deleteLogo

deleteLogo(instanceId: string, opts?: CallOptions)

Remove the logo of an instance. Back to the default logo of the runtime: the branding no longer points to an object, version is incremented and the stored object is removed. Without a logo, answers the branding unchanged. Same rights as the PUT; audited as compliance.branding.logo.remove.

Route: /v1/compliance/instances/{instance_id}/branding/logo (DELETE).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.get

get(instanceId: string, opts?: CallOptions)

Read a Compliance & Audit Agent instance. The activation record with serving (true for ready and degraded), sector, pack, the current operation and run, validation, last_error and the steps of the current run in order (state, attempts, detail, logs, times). This is the route the compliance runtime reads at startup and on demand.

Route: /v1/compliance/instances/{instance_id} (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance, the same in the Control Plane and in the compliance runtime.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.getBranding

getBranding(instanceId: string, opts?: CallOptions)

Read the branding of an instance. The branding chosen in the activation journey, owned by the Control Plane: agent_name, sidebar_color, navbar_color, the text colours computed for them (sidebar_text_color, navbar_text_color, black or white, contrast 4.5:1 or more), logo (content_type, sha256, size_bytes, url) or null, version, updated_at, and app_url (the URL of the web application once known). A null field means the default of the runtime. The compliance runtime keeps a replica of it for its public login page and rewrites it when version is newer. Any principal of the tenant; another tenant's instance answers 404.

Route: /v1/compliance/instances/{instance_id}/branding (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.getLogo

getLogo(instanceId: string, opts?: CallOptions)

Read the logo of an instance. The logo bytes, read from the storage domain and checked against the recorded sha256, with the Content-Type of the validated format (image/png or image/jpeg), X-Content-Type-Options: nosniff, a Content-Security-Policy starting with default-src 'none' and an ETag. 404 compliance_logo_not_found when the instance has no logo. Any principal of the tenant.

Route: /v1/compliance/instances/{instance_id}/branding/logo (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.health

health(instanceId: string, opts?: CallOptions)

Health of an instance. Real checks: readiness URL of the runtime (GET /readyz), knowledge base (row, vector store qdrant, Qdrant /readyz) and model gateway (generation and embedding models in the registry, usable). status is up, degraded or down (runtime down); instance_status is the lifecycle status. Each check has status, duration_ms and reason when not up.

Route: /v1/compliance/instances/{instance_id}/health (GET).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.list

list(query?: { status?: string; project?: string; sector?: string; limit?: number }, opts?: CallOptions)

List the Compliance & Audit Agent instances. Activation records of the tenant, newest first, with status, sector, pack, deployment model, versions and owned resources (one page, next_cursor null). Filters: status, project, sector.

Route: /v1/compliance/instances (GET).

Name	Type	Default	Required	Description
query	{ status?: string; project?: string; sector?: string; limit?: number }		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.provision

provision(instanceId: string, opts?: CallOptions)

Provision an instance. Long operation (202, Operation-Id): status provisioning then starting, steps from validation to activation run by the worker. From a validated draft (else 409 compliance_not_validated) or after a failed provisioning, which resumes from the failed step. Repeated while provisioning or once ready: changed: false. Audited as compliance.provision, each step as compliance.step.

Route: /v1/compliance/instances/{instance_id}/provision (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.restart

restart(instanceId: string, opts?: CallOptions)

Restart an instance. Long operation (202): from ready, degraded, stopped or after a failed restart, steps deployment (Navin Manager restart for a dedicated instance), health, smoke, activation. A restart in progress: changed: false.

Route: /v1/compliance/instances/{instance_id}/restart (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.restore

restore(instanceId: string, backupId: string, opts?: CallOptions)

Restore an instance (not supported). Answers 501 compliance_backup_not_supported with the same parts as the backup: no backup of an instance can be made for real yet. Audited.

Route: /v1/compliance/instances/{instance_id}/restore (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
backupId	string		yes	Identifier of the backup to restore.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.start

start(instanceId: string, opts?: CallOptions)

Start an instance. Long operation (202): from stopped (or after a failed start or stop), steps deployment (Navin Manager start for a dedicated instance, status only for a shared one), health, smoke, activation (governed application active). Already starting or ready: changed: false.

Route: /v1/compliance/instances/{instance_id}/start (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.stop

stop(instanceId: string, opts?: CallOptions)

Stop an instance. Long operation (202): from ready, degraded or after a failed start, restart, upgrade or stop, steps deployment (Navin Manager stop for a dedicated instance, status only for a shared one) and activation (governed application suspended, reason compliance_instance_stopped); status stopped. Already stopping or stopped: changed: false.

Route: /v1/compliance/instances/{instance_id}/stop (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.updateBranding

updateBranding(instanceId: string, body: RagAgentBrandingUpdate, opts?: CallOptions)

Change the branding of an instance. Writes the fields given (an absent field is kept, null brings it back to the default of the runtime) and answers the branding. Colours are #RRGGBB (stored in upper case); the text drawn on them is black or white, whichever contrasts most (WCAG 2.2 relative luminance), and a colour whose text would stay under 4.5:1 answers 422 compliance_branding_contrast. app_url must be an https URL without credentials (422 compliance_app_url_invalid). A change of the name, the colours or the logo increments version; expected_version different from the current one answers 409 compliance_branding_version_conflict. With an Idempotency-Key, a retry with the same body replays the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Needs a tenant administrator or an owner of the project (403 forbidden); refused while the instance is deleting or deleted (409). Audited as compliance.branding.update.

Route: /v1/compliance/instances/{instance_id}/branding (PUT).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
body	RagAgentBrandingUpdate		yes	The branding fields to write.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.upgrade

upgrade(instanceId: string, version: string, opts?: CallOptions)

Upgrade an instance. Long operation (202), status updating: a shared instance follows the shared runtime, so the deployment step reads the version of the runtime in its OpenAPI document (GET /api/v1/compliance/openapi.json) and checks that it is the requested one (else shared_runtime_version_mismatch); a dedicated one is reinstalled by the Navin Manager. Then health, smoke, activation; deployed_version becomes the version. The same version already deployed or in progress: changed: false.

Route: /v1/compliance/instances/{instance_id}/upgrade (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
version	string		yes	Version to deploy (letters, digits, ., _, +, -, up to 64 characters).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.uploadLogo

uploadLogo(instanceId: string, input: RagAgentLogoUpload | FormData, opts?: CallOptions)

Upload the logo of an instance. Multipart file (with the optional text fields filename and mime_type). PNG or JPEG only: SVG and any other format are refused. The real signature, the declared Content-Type and the file extension must match; 32 to 1024 pixels a side, 512 KiB at most; else 422 compliance_logo_invalid with details.reason (format_not_allowed, signature_invalid, signature_mismatch, extension_mismatch, dimensions_out_of_bounds, too_large, empty). The file is then scanned by the file security domain, fail closed: a blocked file answers 422 file_blocked, a scanner down 503 file_scan_unavailable. It is stored through the storage domain in the documents storage profile of the tenant under compliance-agent/<tenant>/<instance>/branding/ (409 compliance_branding_storage_required without such a profile, 503 compliance_branding_storage_unavailable when it cannot be reached); the replaced object is removed. Increments version and answers the branding. Same rights as the PUT; audited as compliance.branding.logo.update (a refusal is audited as a denial).

Route: /v1/compliance/instances/{instance_id}/branding/logo (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
input	RagAgentLogoUpload | FormData		yes
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

ComplianceResource.validate

validate(instanceId: string, opts?: CallOptions)

Validate an instance. Real checks before provisioning: the project exists and the caller may administer it, the generation model exists in the registry with the chat capability and a usable status, the embedding model resolves in the Model Gateway (capability embeddings), the quota of instances, Qdrant answers, the shared runtime answers (shared model) or the Navin Manager answers (dedicated model, an unpublished catalog service is a warning). From draft or after a failed validation. 200 with validation and status draft; 422 compliance_validation_failed with the failed checks (status failed, step validation). Audited as compliance.validate and compliance.validate.completed.

Route: /v1/compliance/instances/{instance_id}/validate (POST).

Name	Type	Default	Required	Description
instanceId	string		yes	Identifier (UUID) of the instance.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface MemoryEngineDeclare

Body of declareEngine: a mem0 or Cognee engine instance of the Navin Memory Provider.

Doc

Fields:

Name	Type	Required	Description
id	string	yes	LiteLLM model_name, unique in the profile.
provider	"mem0" | "cognee"	yes	Engine of the instance: mem0 or cognee.
base_url	string	yes	Address of the API rendered by the Navin Manager (https in staging and prod).
tenant_id	string	no	Tenant of the agent. Default default.
credential_ref	string	no	Reference of the credential in the secret store; the credential itself is never sent.
access_control	boolean	no	Cognee only: the instance runs with backend access control (one user per tenant gives a backend separation).
tls_verify	boolean	no	Whether the TLS certificate of the server is verified. Keep it true outside a sandbox.
timeout_seconds	number	no	Timeout of a call to the engine, in seconds (at most 300).
manager_cluster	string	no	Platform Manager cluster that installed the engine.
manager_service	string	no	Platform Manager service of the engine.

Interface AgentMemoryWrite

Body of remember: one memory of the agent, stored by the engine of its policy.

Doc

Fields:

Name	Type	Required	Description
content	string	yes	Text of the memory (at most 20000 characters).
scope	string	no	What is backed up (clusters, services, data sets), as an object.
kind	"episodic" | "semantic" | "procedural" | "preference" | "fact"	no	Kind of memory: episodic, semantic, procedural, preference or fact.
classification	"public" | "internal" | "confidential" | "restricted"	no	Classification: public, internal, confidential or restricted.
session_id	string	no	Session of the memory, for the session scope.
team	string	no	Team of the memory, for the team scope.
retention_days	number	no	Days a backup is kept before it can be deleted, 1 or more.
legal_hold	boolean	no	Keeps the memory under legal hold: it cannot be forgotten or purged.
source	{ source_type: string; source_id: string; uri?: string; version?: string }	no	Origin of the memory: source_type, source_id, uri and version.

Interface AgentMemoryRecall

Body of recall and searchMemories.

Doc

Fields:

Name	Type	Required	Description
query	string	yes	Text searched in the memories of the agent.
scopes	string[]	no	Scopes requested; must include openid. Default openid, profile, email.
top_k	number	no	Number of memories returned (1 to 50).
session_id	string	no	Session whose memories are searched with the session scope.

Class RetentionResource

Retention. How long the data of the tenant is kept, how it is purged, the erasure of a data subject (GDPR article 17) and legal holds.

Resource

RetentionResource.createPolicy

createPolicy(body: Doc, opts?: CallOptions)

Create or update a retention policy. Sets the retention policy of one resource type, replacing the existing one. Needs tenant_admin, security_officer or data_steward. An unknown resource type or an action other than erase or archive answers 400 invalid_request. The policy takes effect at the next retention run. Writes the audit event retention.policy.upsert. Answers 201 with the policy.

Route: /v1/retention/policies (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Resource type, lifetime and action of the policy.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RetentionResource.erase

erase(body: { subject_id: string } & Doc, opts?: CallOptions)

Erase a data subject. Deletes the data held on one subject, in one transaction. Needs tenant_admin, security_officer or data_steward.

Route: /v1/retention/erase (POST).

Name	Type	Default	Required	Description
body	{ subject_id: string } & Doc		yes	Subject, scope and reason of the erasure.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RetentionResource.legalHold

legalHold(body: Doc, opts?: CallOptions)

Place or release a legal hold. Without hold_id, places a new hold on a subject (subject_id) or on one resource (resource_type and resource_id); reason is required (400 invalid_request otherwise). With hold_id, activates or releases that hold with active (404 not_found for an unknown hold).

Route: /v1/retention/legal-hold (POST).

Name	Type	Default	Required	Description
body	Doc		yes	New hold, or the identifier of a hold to activate or release.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RetentionResource.listPolicies

listPolicies(params?: ListParams, opts?: CallOptions)

List the retention policies. Returns the retention policies of the tenant ordered by resource type in items, and the active legal holds in legal_holds. Open to any member of the tenant. next_cursor is always null.

Route: /v1/retention/policies (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

RetentionResource.run

run(body: Doc = {}, opts?: CallOptions)

Run the retention policies. Applies the enabled policies now, to every resource type or to resource_types. Memory items and media past their own expiry are purged even without a policy; realtime transcripts and recordings follow the retention period of the participant consent. Items under legal hold are skipped.

Route: /v1/retention/run (POST).

Name	Type	Default	Required	Description
body	Doc	{}	no	Optional simulation flag and resource types. An empty body runs every policy for real.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class LineageResource

Lineage. Data lineage of the tenant, fed with OpenLineage events: which jobs read which datasets and produce which others.

Resource

LineageResource.dataset

dataset(id: string, opts?: CallOptions)

Get the lineage of a dataset. Returns the dataset node, the jobs that produce it (produced_by), the jobs that consume it (consumed_by) and its upstream and downstream graphs up to depth hops. Open to any member of the tenant. Answers 404 not_found for an unknown dataset.

Route: /v1/lineage/datasets/{dataset_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Dataset key, dataset:<namespace>:<name> or <namespace>:<name> (the prefix is added), URL encoded.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

LineageResource.emit

emit(body: Doc | Doc[], opts?: CallOptions)

Send OpenLineage events. Accepts one OpenLineage RunEvent or {"events": [RunEvent, ...]}, in one transaction. Each event needs run.runId and job.namespace and job.name; eventType is one of START, RUNNING, COMPLETE, ABORT, FAIL or OTHER (default; any other answers 400); eventTime defaults to the reception time.

Route: /v1/lineage/events (POST).

Name	Type	Default	Required	Description
body	Doc | Doc[]		yes	One OpenLineage RunEvent, or an object events holding a list of them.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

LineageResource.graph

graph(query?: Query, opts?: CallOptions)

Get the lineage graph. Returns nodes and edges. With node, the graph is walked from that node in direction up to depth hops (404 not_found for an unknown node). Without node, returns up to limit job and dataset nodes ordered by key, and the edges between them. A direction other than both, upstream or downstream answers 400 invalid_request. Open to any member of the tenant.

Route: /v1/lineage/graph (GET).

Name	Type	Default	Required	Description
query	Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Class PromptsResource

Prompts. Prompt registry: versioned prompt templates with typed variables and validated rendering.

Resource

PromptsResource.create

create(body: Doc, opts?: CallOptions)

Publish a prompt version. Creates a prompt, or publishes a new version when the name exists; identical templates and variables are not duplicated (the current version is returned). The name is lowercase letters, digits, ., _, - (1 to 128 characters, 400 invalid_request otherwise). An unbalanced placeholder, an unknown variable type or a placeholder not declared in variables answers 422 template_error. Needs tenant_admin or developer. Audited as prompt.publish.

Route: /v1/prompts (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Name, template, description, variables and model hint.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PromptsResource.list

list(params?: ListParams, opts?: CallOptions)

List the prompts. Prompts of the tenant in name order with their latest version number, paginated with cursor.

Route: /v1/prompts (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PromptsResource.render

render(name: string, body: { variables?: Doc; version?: string } & Doc, opts?: CallOptions)

Render a prompt. Fills the template of a version (default: the latest) with the given values and returns text, chars and estimated_tokens (characters divided by 4). Missing required values, wrong types, values outside enum, values over max_length and, with strict, unknown variables answer 422 missing_variables with one entry per problem. 404 not_found for an unknown prompt or version. Nothing is stored.

Route: /v1/prompts/{name}/render (POST).

Name	Type	Default	Required	Description
name	string		yes	Name of the prompt.
body	{ variables?: Doc; version?: string } & Doc		yes	Values of the variables, version and strict mode.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

PromptsResource.versions

versions(name: string, opts?: CallOptions)

List the versions of a prompt. The prompt and every version, newest first, with template, variables, model hint, digest and author. 404 not_found.

Route: /v1/prompts/{name}/versions (GET).

Name	Type	Default	Required	Description
name	string		yes	Name of the prompt.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).