io.enterpriseai.resources.RagAgentClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/RagAgentClient.java. Back to the Java SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class RagAgentClient
Navin Enterprise RAG Agent instances: activation and lifecycle owned by the Control Plane.
Constructor RagAgentClient
RagAgentClient(Transport transport)
Creates the client on the shared transport; EnterpriseAIClient builds it and exposes it through the accessor of the same name.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
transport | Transport | yes | Transport shared by the sub-clients of one client. |
RagAgentClient.backup
JsonNode backup(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Back up an instance (not supported)".
Raises: the typed errors of the transport (Errors).
RagAgentClient.check
JsonNode check(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Validate an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.create
JsonNode create(Object body, RequestOptions options)
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 | Object | yes | Name, project, organization and business unit, deployment model, generation and embedding models of the registry, optional version. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Create a draft RAG Agent instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.delete
JsonNode delete(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Delete an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.deleteLogo
JsonNode deleteLogo(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Remove the logo of an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.get
JsonNode get(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Read a RAG Agent instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.getBranding
JsonNode getBranding(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Read the branding of an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.getLogo
byte[] getLogo(String instanceId)
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. |
Returns: byte[]. Decoded JSON answer of the operation "Read the logo of an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.health
JsonNode health(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Health of an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.list
JsonNode list(Map<String, ?> query)
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 | Map<String, ?> | yes | Query string parameters of the route. |
Returns: JsonNode. Decoded JSON answer of the operation "List the RAG Agent instances".
Raises: the typed errors of the transport (Errors).
RagAgentClient.provision
JsonNode provision(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Provision an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.restart
JsonNode restart(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Restart an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.restore
JsonNode restore(String instanceId, String backupId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Restore an instance (not supported)".
Raises: the typed errors of the transport (Errors).
RagAgentClient.start
JsonNode start(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Start an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.stop
JsonNode stop(String instanceId)
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. |
Returns: JsonNode. Decoded JSON answer of the operation "Stop an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.updateBranding
JsonNode updateBranding(String instanceId, Object body, RequestOptions options)
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 | Object | yes | The branding fields to write. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Change the branding of an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.upgrade
JsonNode upgrade(String instanceId, String version)
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). |
Returns: JsonNode. Decoded JSON answer of the operation "Upgrade an instance".
Raises: the typed errors of the transport (Errors).
RagAgentClient.uploadLogo
JsonNode uploadLogo(String instanceId, byte[] data, String filename, String mimeType)
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. | |
data | byte[] | yes | Multipart form with the logo in the file part. | |
filename | String | yes | Name of the logo file; its extension must match the real format (.png, .jpg or .jpeg). | |
mimeType | String | yes | Media type of the content, for example application/pdf or image/png. |
Returns: JsonNode. Decoded JSON answer of the operation "Upload the logo of an instance".
Raises: the typed errors of the transport (Errors).