endpoints_v12.go (package eai)
Source: sdks/go/endpoints_v12.go. Back to the Go SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class MembersService
MembersService groups the endpoints of: Tenant members and role assignment.
MembersService.ChangePassword
ChangePassword(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)
Change the password. Changes the password of the signed in local account. Only for a portal session (403 password_session_required).
Route: /v1/auth/password (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
body | any | yes | Current and new password. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Change the password". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.CreateGroupMapping
CreateGroupMapping(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)
Create a group mapping. Maps a directory group to a project role and, optionally, a quota profile. Needs tenant_admin.
Route: /v1/identity/group-mappings (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
body | any | yes | Group, project, role and optional quota profile of the mapping. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Create a group mapping". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.CreateQuotaProfile
CreateQuotaProfile(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)
Create a quota profile. Creates a reusable quota profile for group mappings. Needs tenant_admin. At least one of limit_cost and limit_tokens is required (422 validation_error). A name already used answers 409 conflict. Writes the audit event identity.quota_profile.create.
Route: /v1/identity/quota-profiles (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
body | any | yes | Name, period, enforcement and limits of the profile. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Create a quota profile". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.DeleteGroupMapping
DeleteGroupMapping(ctx context.Context, mappingID string, opts ...CallOption) error
Delete a group mapping. Deletes the mapping and withdraws what it granted (project memberships and quotas recorded as granted by this mapping); memberships granted by hand stay. Needs tenant_admin. Writes the audit event identity.group_mapping.delete. Answers 204, or 404 not_found for an unknown mapping.
Route: /v1/identity/group-mappings/{mapping_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
mappingID | string | yes | Identifier (UUID) of the group mapping. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.DeleteQuotaProfile
DeleteQuotaProfile(ctx context.Context, profileID string, opts ...CallOption) error
Delete a quota profile. Deletes a quota profile. Needs tenant_admin. A profile still used by a group mapping cannot be deleted (409 conflict): detach it from the mappings first. Writes the audit event identity.quota_profile.delete. Answers 204, or 404 not_found.
Route: /v1/identity/quota-profiles/{profile_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
profileID | string | yes | Identifier (UUID) of the quota profile. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.GetGroupMapping
GetGroupMapping(ctx context.Context, mappingID string, opts ...CallOption) (json.RawMessage, error)
Get a group mapping. Returns one group mapping. Needs tenant_admin, security_officer or auditor. Answers 404 not_found for an unknown mapping.
Route: /v1/identity/group-mappings/{mapping_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
mappingID | string | yes | Identifier (UUID) of the group mapping. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Get a group mapping". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.ListGroupMappings
ListGroupMappings(ctx context.Context, opts ...CallOption) (*Page, error)
List the group mappings. Lists every directory group mapping of the tenant with its group, project, role and quota profile. Needs tenant_admin, security_officer or auditor (403 forbidden otherwise). Not paginated: next_cursor is always null.
Route: /v1/identity/group-mappings (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (*Page, error). A Page: Page is one page of a cursor paginated collection {"items": [...], "next_cursor": "..."|null}. The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.ListQuotaProfiles
ListQuotaProfiles(ctx context.Context, opts ...CallOption) (*Page, error)
List the quota profiles. Lists the quota profiles of the tenant (name, period, enforcement, cost and token limits, currency). Needs tenant_admin, security_officer or auditor.
Route: /v1/identity/quota-profiles (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (*Page, error). A Page: Page is one page of a cursor paginated collection {"items": [...], "next_cursor": "..."|null}. The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.Login
Login(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)
Sign in with a login and a password. Opens a portal session for a local account. No credential is needed. The login is compared without case.
Route: /v1/auth/login (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
body | any | yes | Login and password of the local account. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Sign in with a login and a password". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.Logout
Logout(ctx context.Context, opts ...CallOption) (json.RawMessage, error)
Sign out. Revokes the current portal session: its token is refused from now on (401 session_revoked). Only for a portal session (403 password_session_required with another credential). Writes the audit event auth.logout. Answers 204.
Route: /v1/auth/logout (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Sign out". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.UpdateGroupMapping
UpdateGroupMapping(ctx context.Context, mappingID string, body any, opts ...CallOption) (json.RawMessage, error)
Update a group mapping. Changes the group, project, role or quota profile of a mapping; only the fields sent change. clear_quota_profile: true detaches the profile. The new values apply at the next sign in of each member. Needs tenant_admin. A change that would duplicate another mapping answers 409 conflict; an unknown project or profile answers 404. Writes the audit event identity.group_mapping.update.
Route: /v1/identity/group-mappings/{mapping_id} (PATCH).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
mappingID | string | yes | Identifier (UUID) of the group mapping. | |
body | any | yes | Fields to change; omitted fields keep their value. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Update a group mapping". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.UpdateQuotaProfile
UpdateQuotaProfile(ctx context.Context, profileID string, body any, opts ...CallOption) (json.RawMessage, error)
Update a quota profile. Updates the period, enforcement or limits of a profile, and the user quotas already created from it through group mappings, in the same transaction. Needs tenant_admin. Writes the audit event identity.quota_profile.update with the number of quotas updated. Answers 404 not_found for an unknown profile.
Route: /v1/identity/quota-profiles/{profile_id} (PATCH).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
profileID | string | yes | Identifier (UUID) of the quota profile. | |
body | any | yes | Fields to change; omitted fields keep their value. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Update a quota profile". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MembersService.WhoAmI
WhoAmI(ctx context.Context, opts ...CallOption) (json.RawMessage, error)
Show the calling identity. Returns the identity the platform resolved for this request, whatever the credential (OIDC token, portal session, API key, SPIFFE): id, kind (user, service, agent, system), tenant_id, tenant_slug, roles, scopes, clearance, auth_method and display. Read only, open to any authenticated caller, also while a local account must still change its password. Use it to check a new token or key.
Route: /v1/identity/whoami (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Show the calling identity". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class IncidentsService
Incidents. Security and operations incidents of the tenant: severity, status, timeline, containment actions, Alertmanager alerts and forwarding to the SIEM.
IncidentsService.ReceiveAlerts
ReceiveAlerts(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)
Receive Alertmanager alerts. Webhook receiver of Prometheus Alertmanager (payload version 4). Each alert is keyed by its fingerprint:
Route: /v1/incidents/alerts (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
body | any | yes | Alertmanager webhook payload, at most 500 alerts. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Receive Alertmanager alerts". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class SkillsService
Skills. Skill Registry and Skill Loader. A skill is a signed, versioned set of instructions (inline, or an artifact in Git or OCI) with the permissions it needs; agents load the skills granted in their manifest.
SkillsService.SetStatus
SetStatus(ctx context.Context, name string, body any, opts ...CallOption) (json.RawMessage, error)
Change the status of a skill. approved goes through a promotion: an approval is opened for tenant_admin or security_officer and the answer is 202 with approval_id and status: pending_approval. The other statuses (draft, restricted, deprecated, blocked) apply at once (200). Needs tenant_admin or security_officer and the ReBAC relation editor. Audited as skill.status.
Route: /v1/skills/{name}/status (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
name | string | yes | Name of the skill. | |
body | any | yes | Target status and reason. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Change the status of a skill". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class MCPService
MCP gateway. Registry of the upstream MCP servers (Model Context Protocol) and the MCP Gateway, a JSON-RPC 2.0 proxy that applies the platform controls to every call: project isolation, allowed callers, allow lists of tools and resources, scopes, DLP, policy, quota, prompt injection screening, metering and audit.
MCPService.Catalog
Catalog(ctx context.Context, opts ...CallOption) (json.RawMessage, error)
Get the MCP tool catalogue. Catalogue: tools, input and output schemas, versions, scopes and approval status (approved, pending_approval, rejected), for the servers the request may see only, as GET /v1/mcp/servers.
Route: /v1/mcp/catalog (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Get the MCP tool catalogue". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MCPService.Connect
Connect(ctx context.Context, serverID string, opts ...CallOption) (json.RawMessage, error)
Call an MCP server through the gateway. JSON-RPC 2.0 proxy. The body is one request or a batch (at most 50 are handled). Needs tenant_admin, developer or agent and the ReBAC relation can_invoke. Refusals are answered as JSON-RPC errors with HTTP 200, and audited. Checks, in order: valid JSON-RPC 2.0; server active; project isolation (mcp_server_project_mismatch); allowed callers (mcp_principal_not_allowed); a sleeping hosted instance is woken up; a third party application must be active and granted the server; method allowed; for tools/call: tool in allowed_tools, scope tools:invoke, DLP on the arguments; policy mcp.call; quota reservation; for resources/read: URI in allowed_resources. Then the call is forwarded with the upstream credentials; tools/list and resources/list are filtered by the allow lists, tools/call results are masked by DLP and screened for prompt injection, and the call is metered as a tool usage.
Route: /v1/mcp/gateway/{server_id} (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
serverID | string | yes | Identifier (UUID) or name of the MCP server. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Call an MCP server through the gateway". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MCPService.DiscoverServer
DiscoverServer(ctx context.Context, serverID string, opts ...CallOption) (json.RawMessage, error)
Discover the tools of an MCP server. MCP protocol discovery (initialize, tools/list): every new or changed tool schema becomes a catalogue version waiting for approval (mcp_tool_version, approvers tenant_admin or security_officer). Returns the versions created with their approval ids. Needs tenant_admin, developer or application_owner, the ReBAC relation editor and access to the project of the server.
Route: /v1/mcp/servers/{server_id}/discover (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
serverID | string | yes | Identifier (UUID) or name of the MCP server. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Discover the tools of an MCP server". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MCPService.SetAccess
SetAccess(ctx context.Context, serverID string, body any, opts ...CallOption) (json.RawMessage, error)
Set who may call an MCP server. MCP Gateway access control: which users and agents may call this server; an empty list lets every member of its project call it. Principal ids are letters, digits and :._@/- (up to 128 characters, 400 invalid_request). The access of a hosted instance is managed by the MCP runtime (409 mcp_instance_access_managed). Needs tenant_admin, developer or application_owner and access to the project of the server. Audited as mcp.server.access.
Route: /v1/mcp/servers/{server_id}/access (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
serverID | string | yes | Identifier (UUID) or name of the MCP server. | |
body | any | yes | The allowed principals. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Set who may call an MCP server". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
MCPService.SetServerStatus
SetServerStatus(ctx context.Context, id string, body any, opts ...CallOption) (json.RawMessage, error)
Enable or disable an MCP server. active goes through a promotion: an approval is opened and the answer is 202 with approval_id. disabled applies at once (every gateway call is then refused) and is audited as mcp.server.status. Needs tenant_admin or security_officer, the ReBAC relation editor and access to the project of the server.
Route: /v1/mcp/servers/{server_id}/status (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
id | string | yes | Identifier (UUID) or name of the MCP server. | |
body | any | yes | Target status and reason. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Enable or disable an MCP server". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class KnowledgeService
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.
KnowledgeService.Chunks
Chunks(ctx context.Context, kbID string, docID string, opts ...CallOption) (*Page, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
docID | string | yes | Identifier (UUID) of the current document. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (*Page, error). A Page: Page is one page of a cursor paginated collection {"items": [...], "next_cursor": "..."|null}. The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.Cite
Cite(ctx context.Context, kbID string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
body | any | yes | Query text and search options. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Query a knowledge base". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.Diagnostics
Diagnostics(ctx context.Context, kbID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the diagnostics of the queries". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.DocumentStatus
DocumentStatus(ctx context.Context, kbID string, docID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
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 | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Read the status of a document". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.IngestionJob
IngestionJob(ctx context.Context, kbID string, jobID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
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 | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Read an ingestion job". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.Quarantine
Quarantine(ctx context.Context, kbID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the quarantined documents". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.Reindex
Reindex(ctx context.Context, id string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
id | string | yes | Identifier (UUID) of the knowledge base. | |
body | any | yes | Target embedding model and dimension. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Reindex with another embedding model". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.ReindexJobs
ReindexJobs(ctx context.Context, id string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
id | string | yes | Identifier (UUID) of the knowledge base. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the reindex jobs". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.Retrieve
Retrieve(ctx context.Context, kbID string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
body | any | yes | Query text and search options. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Query a knowledge base". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.RetryIngestion
RetryIngestion(ctx context.Context, kbID string, jobID string, reason string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
jobID | string | yes | Identifier (UUID) of the failed ingestion job. | |
reason | string | yes | Why the action is taken. Written to the audit trail with the actor and the time. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Retry a failed ingestion job". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.ReviewDocument
ReviewDocument(ctx context.Context, kbID string, docID string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
docID | string | yes | Identifier (UUID) of the document. | |
body | any | yes | Decision and reason. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Review a quarantined document". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.SetRetrieval
SetRetrieval(ctx context.Context, kbID string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
body | any | yes | The retrieval strategy. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Set the retrieval strategy". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.UploadDocument
UploadDocument(ctx context.Context, kbID string, upload DocumentUpload, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
upload | DocumentUpload | yes | The file (Content, sent as content_base64), its format and its metadata. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Upload a document for asynchronous ingestion". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
KnowledgeService.Versions
Versions(ctx context.Context, kbID string, docID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
kbID | string | yes | Identifier (UUID) of the knowledge base. | |
docID | string | yes | Identifier (UUID) of the document or of one of its past versions. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the versions of a document". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).