resources/tools.ts

Source: sdks/typescript/packages/sdk/src/resources/tools.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 ToolsResource

Tool registry (/v1/tools) and Tool Gateway invocation, where scopes, policy, DLP, approval and cost are enforced server side.

Resource

Attributes:

Name	Type	Required	Description
body	{ arguments?: Doc; run_id?: string; agent_id?: string; approval_id?: string; purpose?: string; data_classification?: "public" | "internal" | "confidential" | "restricted" | "secret" } & Doc,	yes	Body of invoke: tool arguments, run, agent, approval, purpose and data classification.
name	string,	yes	Name of the tool called by invoke.
opts	CallOptions) {	no	Per call options of invoke.

ToolsResource.create

create(body: Doc, opts?: CallOptions)

Register a tool. Applies a Tool manifest: creates or updates the tool (apply_status: created, updated or unchanged). Checked: valid JSON Schemas for input and output, an http endpoint needs an http(s) URL allowed by the egress policy, an mcp endpoint needs mcp_server, a builtin handler must be echo or time.now, risk level unacceptable is refused (422 invalid_manifest). Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as tool.apply.

Route: /v1/tools (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Tool manifest (kind: Tool, metadata, spec with description, action, input schema, endpoint, data classification and options).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ToolsResource.delete

delete(name: string, opts?: CallOptions)

Delete a tool. Removes the tool from the registry. Needs tenant_admin and the ReBAC relation owner. 404 tool_not_found. Audited as tool.delete.

Route: /v1/tools/{name} (DELETE).

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

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

ToolsResource.discover

discover(query: { status?: string } = { status: "approved" }, opts?: CallOptions)

List the tools. Tools of the tenant in name order, optionally with one status. One page only.

Route: /v1/tools (GET).

Name	Type	Default	Required	Description
query	{ status?: string }	{ status: "approved" }	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).

ToolsResource.get

get(name: string, opts?: CallOptions)

Get a tool. Returns the tool with its manifest, risk level, owner and status. Needs the ReBAC relation viewer. 404 tool_not_found.

Route: /v1/tools/{name} (GET).

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

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

ToolsResource.invocations

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

List the tool invocations. Invocations recorded by the Tool Gateway, newest first, paginated with cursor: tool and version, actor, run, agent, status, decision, approval, redacted arguments and result, DLP findings, HTTP status, error and duration. Arguments and results are stored redacted only.

Route: /v1/tools/invocations (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).

ToolsResource.invoke

invoke(name: string, body: { arguments?: Doc; run_id?: string; agent_id?: string; approval_id?: string; purpose?: string; data_classification?: "public" | "internal" | "confidential" | "restricted" | "secret" } & Doc, opts?: CallOptions)

Invoke a tool through the gateway. Runs the gateway pipeline described in the tag introduction and returns the invocation: status, masked result, error, duration_ms, decision_id, DLP findings, usage event and cost. Needs tenant_admin, developer or agent and the ReBAC relation can_invoke. Answers: 200 when executed (also when the upstream failed, see status and error); 202 pending_approval with approval_id when a human approval is needed (call again with the approved approval_id and the same arguments); 202 for a sandbox tool, with the sandbox execution id. Errors: 403 tool_blocked, insufficient_scope, tool_not_granted, classification_exceeded, policy_denied, dlp_blocked; 422 invalid_arguments; 409 approval_consumed (an approval serves one successful call); 429 rate_limited with Retry-After: 60 or quota_exceeded.

Route: /v1/tools/{name}/invoke (POST).

Name	Type	Default	Required	Description
name	string		yes	Name of the tool.
body	{ arguments?: Doc; run_id?: string; agent_id?: string; approval_id?: string; purpose?: string; data_classification?: "public" | "internal" | "confidential" | "restricted" | "secret" } & Doc		yes	Arguments of the call and its context (run, agent, approval, purpose, classification).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ToolsResource.list

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

List the tools. Tools of the tenant in name order, optionally with one status. One page only.

Route: /v1/tools (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).

ToolsResource.update

update(name: string, body: Doc, opts?: CallOptions)

Update a tool. Changes the owner, the description or the status. A status change needs tenant_admin or security_officer, other fields tenant_admin, developer or application_owner; the ReBAC relation editor is checked. approved goes through a promotion (202 with approval_id); other statuses apply at once (200). Audited as tool.update.

Route: /v1/tools/{name} (PATCH).

Name	Type	Default	Required	Description
name	string		yes	Name of the tool.
body	Doc		yes	Fields to change; the omitted ones are kept.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ToolsResource.validate

validate(manifest: Doc, opts?: CallOptions)

Validate a document against a contract. Validates the body against the contract, formats included, without storing anything. The answer gives contract, valid and errors, each with the JSON path of the faulty value and a message. Open to any authenticated caller. An unknown contract answers 404 unknown_contract.

Route: /v1/contracts/{name}/validate (POST).

Name	Type	Default	Required	Description
manifest	Doc		yes	Tool Manifest to validate on the server.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Interface JsonRpcResponse

JSON-RPC 2.0 answer of the MCP gateway: a result or an error.

Fields:

Name	Type	Required	Description
jsonrpc	"2.0"	yes	Always 2.0.
id	number | string | null	yes	Id of the request this answer matches.
result	T	no	Result of the call.
error	{ code: number; message: string; data?: unknown }	no	RPC error: code, message and data; rpc throws mcp_error when it is set.

Class McpResource

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.

Resource

McpResource.callTool

callTool(serverId: string, name: string, args: Doc = {}, opts?: CallOptions)

Calls a tool of an MCP server (JSON-RPC tools/call) through the MCP gateway.

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
name	string		yes	Name of the tool on the MCP server.
args	Doc	{}	no	Arguments of the tool (default an empty object).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.catalog

catalog(query: { server?: string } = {}, opts?: CallOptions)

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
query	{ server?: string }	{}	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).

McpResource.connect

connect(serverId: string, opts?: CallOptions)

JSON-RPC initialize through the MCP gateway: the server information (an RPC error throws).

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.deleteServer

deleteServer(id: string, opts?: CallOptions)

Delete an MCP server. Removes the server from the registry. Needs tenant_admin, the ReBAC relation owner and access to the project of the server. 404 mcp_server_not_found. Audited as mcp.server.delete.

Route: /v1/mcp/servers/{server_id} (DELETE).

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

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

McpResource.discover

discover(serverId: string, opts?: CallOptions)

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
serverId	string		yes	Identifier (UUID) or name of the MCP server.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

McpResource.initialize

initialize(serverId: string, params: Doc = { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "@enterprise-ai/sdk", version: "1.0.0" } }, opts?: CallOptions)

JSON-RPC initialize through the MCP gateway, with protocol 2024-11-05 and the SDK client info by default.

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
params	Doc	{ protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "@enterprise-ai/sdk", version: "1.0.0" } }	no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.listPrompts

listPrompts(serverId: string, opts?: CallOptions)

Lists the prompts of an MCP server (JSON-RPC prompts/list).

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.listResources

listResources(serverId: string, opts?: CallOptions)

Lists the resources of an MCP server (JSON-RPC resources/list).

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.listServers

listServers(params?: ListParams & { project?: string }, opts?: CallOptions)

List the MCP servers. Servers the request may see: project (id or slug) keeps the servers of that project; a request made in a project (X-Project header or an API key bound to a project) sees the servers of its project and those shared by the tenant, never those of another project (403 mcp_project_forbidden). Upstream secrets are never returned, only their references.

Route: /v1/mcp/servers (GET).

Name	Type	Default	Required	Description
params	ListParams & { project?: 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).

McpResource.listTools

listTools(serverId: string, opts?: CallOptions)

Lists the tools of an MCP server (JSON-RPC tools/list).

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.readResource

readResource(serverId: string, uri: string, opts?: CallOptions)

Reads a resource of an MCP server (JSON-RPC resources/read).

Name	Type	Default	Required	Description
serverId	string		yes	Id of the registered MCP server.
uri	string		yes	URI of the resource to read.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

McpResource.registerServer

registerServer(body: { name: string; url: string; transport?: "sse" | "streamable_http"; auth?: Doc; owner?: string; allowed_tools?: string[]; allowed_resources?: string[] } & Doc, opts?: CallOptions)

Register an MCP server. Registers an upstream server (201). The URL must be http(s) on an internal host allowed by the MCP egress policy (403 mcp_online_forbidden otherwise); bearer, api_key and query_param need an openbao:// or env:// credential_ref, query_param needs param, connector needs connector (400 invalid_request). A name already used answers 409 conflict. The project (default X-Project) must be the request project (403 mcp_project_forbidden). Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as mcp.server.create.

Route: /v1/mcp/servers (POST).

Name	Type	Default	Required	Description
body	{ name: string; url: string; transport?: "sse" | "streamable_http"; auth?: Doc; owner?: string; allowed_tools?: string[]; allowed_resources?: string[] } & Doc		yes	Name, URL, transport, upstream authentication, allow lists, owner and project.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

McpResource.serverTools

serverTools(id: string, opts?: CallOptions)

List the tools of an MCP server. Calls tools/list on the server through the gateway and returns the tools allowed by allowed_tools. Needs the ReBAC relation can_invoke and access to the project of the server. An upstream error answers 502 upstream_error.

Route: /v1/mcp/servers/{server_id}/tools (GET).

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

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

McpResource.setAccess

setAccess(serverId: string, principals: string[], opts?: CallOptions)

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
serverId	string		yes	Identifier (UUID) or name of the MCP server.
principals	string[]		yes	Users and agents (principal ids, up to 200) allowed to call the server; empty: every member of its project.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

McpResource.setServerStatus

setServerStatus(id: string, body: { status: string; reason?: string }, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the MCP server.
body	{ status: string; reason?: string }		yes	Target status and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

McpResource.syncHosted

syncHosted(query?: { project?: string }, opts?: CallOptions)

Publish the MCP servers hosted by the Navin Manager. Publishes the MCP servers hosted by the Navin Manager (service mcp-host) in their project: token kept in the Credential Broker, server of the project created or updated, servers no longer hosted disabled. project (id or slug, default the request project) limits the synchronisation to one project; a project other than the request one answers 403 mcp_project_forbidden. Needs tenant_admin and a tenant (403 tenant_required).

Route: /v1/mcp/hosted/sync (POST).

Name	Type	Default	Required	Description
query	{ project?: string }		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 SkillsResource

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.

Resource

SkillsResource.create

create(body: Doc, opts?: CallOptions)

Register a skill. Applies a Skill manifest: creates the skill or replaces it (a replaced skill goes back to draft, a blocked one stays blocked). The digest and the signature are verified at once: the skill becomes approved when they verify. A Git or OCI artifact needs artifact.digest (422 invalid_manifest). apply_status is created or updated. Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as skill.apply.

Route: /v1/skills (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Skill manifest (kind: Skill, metadata with name, version and owner, spec with description, instructions, permissions, signature and optional artifact).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SkillsResource.get

get(name: string, opts?: CallOptions)

Get a skill. Returns the skill with its manifest, content, digest, signature and verification. Needs the ReBAC relation viewer. 404 skill_not_found.

Route: /v1/skills/{name} (GET).

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

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

SkillsResource.list

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

List the skills. Skills of the tenant in name order, with version, owner, digest, verification result and status. One page only.

Route: /v1/skills (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).

SkillsResource.load

load(name: string, opts?: CallOptions)

Load a skill for an agent. Skill Loader: returns what a runtime needs to use the skill (instructions of an inline skill, artifact, entrypoint, permissions, dependencies, signer). Needs the ReBAC relation can_invoke. Refusals, each audited as skill.load denied: - 403 skill_blocked: the skill is blocked or deprecated; - 409 skill_digest_mismatch: the content no longer matches its digest; - 403 skill_unsigned: the signature does not verify; - 403 skill_not_granted: with agent, the skill is not listed in the agent manifest; - 403 skill_permission_denied: the skill asks for scopes the agent lacks, or its classification ceiling is below the agent one.

Route: /v1/skills/{name}/load (GET).

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

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

SkillsResource.setStatus

setStatus(name: string, body: { status: string; reason?: string }, opts?: CallOptions)

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
name	string		yes	Name of the skill.
body	{ status: string; reason?: string }		yes	Target status and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SkillsResource.verify

verify(name: string, opts?: CallOptions)

Verify a skill signature. Checks again the content digest and the signature against the trusted keys and stores the result: verified, method, signer, reason. A verified skill becomes approved, otherwise draft (a blocked skill stays blocked). Needs tenant_admin, developer, application_owner or security_officer and the ReBAC relation editor. Audited as skill.verify.

Route: /v1/skills/{name}/verify (POST).

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

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

Class PluginsResource

Plugins. Registry and runtime lifecycle of plugins: signed OCI images run by the platform in a sandbox (gVisor, Kata or Wasm runtime class), with a Kubernetes Deployment and a NetworkPolicy rendered from the manifest.

Resource

PluginsResource.create

create(body: Doc, opts?: CallOptions)

Register a plugin. Applies a Plugin manifest: creates the plugin or updates it (back to registered, a blocked plugin stays blocked), with the signature verified and stored. Refused: 422 pack_requires_marketplace for a pack, 422 invalid_manifest when the oci_ref digest differs from artifact.digest, an allow list is missing for egress_allowlist or the limits exceed the platform maximum (4 CPU, 8Gi memory, 3600 s, 1 GPU); 409 plugin_installed while installed. Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as plugin.apply.

Route: /v1/plugins (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Plugin manifest (kind: Plugin, metadata, spec with description, artifact, signature and sandbox).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

PluginsResource.get

get(name: string, opts?: CallOptions)

Get a plugin. Returns the plugin with its manifest, verification result and rendered deployment. Needs the ReBAC relation viewer. 404 plugin_not_found.

Route: /v1/plugins/{name} (GET).

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

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

PluginsResource.install

install(name: string, opts?: CallOptions)

Install a plugin. Installs the plugin in its sandbox. Needs tenant_admin and the ReBAC relation owner. Steps: 1. A blocked plugin answers 403 plugin_blocked; an installed one is returned as is. 2. The signature is verified again (403 plugin_unsigned when it fails, audited as a denial). 3. The Deployment (runtime class of the sandbox, read-only root file system by default) and the NetworkPolicy are rendered, then applied when Kubernetes is configured (status: failed with the error if the apply fails). Returns the runtime status. Audited as plugin.install.

Route: /v1/plugins/{name}/install (POST).

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

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

PluginsResource.list

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

List the plugins. Plugins of the tenant in name order, with version, digest, verification and status. One page only.

Route: /v1/plugins (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).

PluginsResource.status

status(name: string, opts?: CallOptions)

Get the runtime status of a plugin. Runtime view: status, verified flag, digest, install date, runtime class, whether the objects were rendered or applied to Kubernetes, the Deployment and NetworkPolicy and the last error. Needs the ReBAC relation viewer.

Route: /v1/plugins/{name}/status (GET).

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

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

PluginsResource.uninstall

uninstall(name: string, opts?: CallOptions)

Uninstall a plugin. Deletes the Deployment and the NetworkPolicy from Kubernetes when configured (502 upstream_error on failure) and sets the plugin to uninstalled. Only an installed, installing or failed plugin (else 409 plugin_not_installed). Needs tenant_admin and the ReBAC relation owner. Audited as plugin.uninstall.

Route: /v1/plugins/{name}/uninstall (POST).

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

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

Class ConnectorsResource

Connectors. Connector Hub: registry of the connections to external systems (SaaS applications, APIs, data sources), their credentials kept server side, synchronisation runs, the Credential Broker that hands short lived leases instead of secrets, and the Webhook Gateway that receives signed provider events.

Resource

ConnectorsResource.create

create(body: Doc, opts?: CallOptions)

Register a connector. Applies a Connector manifest: creates or updates the connector (apply_status: created or updated). The URLs must be allowed by the egress policy; OAuth2 needs auth.token_url; unsigned webhooks are refused (422 invalid_manifest). Needs tenant_admin, developer or application_owner. Audited as connector.apply.

Route: /v1/connectors (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Connector manifest (kind: Connector, metadata, spec with base URL, auth, resources, scopes, sync and webhooks).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ConnectorsResource.delete

delete(name: string, opts?: CallOptions)

Delete a connector. Deletes the connector and its credentials in the secret store. Needs tenant_admin. 404 connector_not_found. Audited as connector.delete.

Route: /v1/connectors/{name} (DELETE).

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

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

ConnectorsResource.get

get(name: string, opts?: CallOptions)

Get a connector. Returns the connector with its manifest, status, owner and configured credentials (kind, field names, update date). 404 connector_not_found.

Route: /v1/connectors/{name} (GET).

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

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

ConnectorsResource.list

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

List the connectors. Connectors of the tenant in name order, each with the kinds of credentials configured (never their values). One page only.

Route: /v1/connectors (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).

ConnectorsResource.setCredentials

setCredentials(name: string, body: Doc, opts?: CallOptions)

Store connector credentials. Stores credentials in the secret store and returns only the kind and the field names (201). Needs tenant_admin or security_officer. Body: kind plus its fields: - oauth2_client: client_id, client_secret; - oauth2_code: code, redirect_uri, optional code_verifier; the code is exchanged at once at the token URL (needs a stored oauth2_client, else 409 credential_unavailable) and kept as oauth2_token; - api_key: api_key, optional header; - service_account: private_key or token, optional client_email, client_id; - basic: username, password; - webhook_secret: secret. Unknown kinds and missing fields answer 400 invalid_request. Audited as connector.credentials.write.

Route: /v1/connectors/{name}/credentials (POST).

Name	Type	Default	Required	Description
name	string		yes	Name of the connector.
body	Doc		yes	Credential kind and its fields. Write only: values are never returned.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ConnectorsResource.sync

sync(name: string, body: Doc = {}, opts?: CallOptions)

Start a synchronisation. Queues a sync run (202) and publishes connectors.<name>.sync for the worker. The manifest must declare a sync mode (409 sync_disabled), the connector must be active (409 connector_disabled), resources must be readable (400 invalid_request) and no other run may be queued or running (409 sync_in_progress). An incremental sync starts from the cursor of the last successful run unless full. The policy connector.sync is evaluated. Needs tenant_admin, developer or agent. Audited as connector.sync.

Route: /v1/connectors/{name}/sync (POST).

Name	Type	Default	Required	Description
name	string		yes	Name of the connector.
body	Doc	{}	no	Optional resources and full flag.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ConnectorsResource.syncRuns

syncRuns(name: string, params?: ListParams, opts?: CallOptions)

List the sync runs of a connector. Synchronisation runs of the connector, newest first: mode, status, resources, cursor and dates.

Route: /v1/connectors/{name}/sync-runs (GET).

Name	Type	Default	Required	Description
name	string		yes	Name of the connector.
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).

ConnectorsResource.test

test(name: string, opts?: CallOptions)

Test a connector. Builds the authentication headers from the stored credentials and, when the manifest has a base URL, sends a GET to it. Returns ok, credentials, http_status, latency_ms and an error code on failure (egress_denied, upstream_unavailable, credential errors); a failed test is a 200 with ok: false. The policy connector.test is evaluated. Needs tenant_admin, developer or application_owner. Audited as connector.test.

Route: /v1/connectors/{name}/test (POST).

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

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

ConnectorsResource.update

update(name: string, body: Doc, opts?: CallOptions)

Update a connector. Changes the status or the owner. Disabling a connector revokes its credential leases at once. Needs tenant_admin, developer or application_owner. Audited as connector.update.

Route: /v1/connectors/{name} (PATCH).

Name	Type	Default	Required	Description
name	string		yes	Name of the connector.
body	Doc		yes	Fields to change; the omitted ones are kept.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class CredentialsResource

Connectors. Connector Hub: registry of the connections to external systems (SaaS applications, APIs, data sources), their credentials kept server side, synchronisation runs, the Credential Broker that hands short lived leases instead of secrets, and the Webhook Gateway that receives signed provider events.

Resource

CredentialsResource.lease

lease(body: { connector: string; scopes?: string[]; ttl_seconds?: number } & Doc, opts?: CallOptions)

Obtain a credential lease. Issues a short lived lease on a connector instead of its secret (201): lease_id, token (shown once), scopes, expires_at, ttl_seconds. Requested scopes must be declared by the connector (403 scope_not_allowed; default: all of them); the connector must be active (409 connector_disabled). With on_behalf_of, the user must hold the relation can_invoke on the connector (403 relation_required). Needs tenant_admin, developer or agent. Audited as credential.lease.

Route: /v1/credentials/broker/lease (POST).

Name	Type	Default	Required	Description
body	{ connector: string; scopes?: string[]; ttl_seconds?: number } & Doc		yes	Connector, scopes, lifetime, run and user acted for.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Interface WebhookHeaders

Headers of a signed webhook: X-EAI-Tenant, X-EAI-Signature and the optional X-EAI-Delivery.

Fields:

Name	Type	Required	Description
X-EAI-Tenant	string	yes	Tenant the webhook is sent for.
X-EAI-Signature	string	yes	Signature t=<unix>,v1=<hex HMAC-SHA256> of <t>.<raw body>.
X-EAI-Delivery	string	no	Delivery id, used to drop duplicates.

Class WebhooksResource

Connectors. Connector Hub: registry of the connections to external systems (SaaS applications, APIs, data sources), their credentials kept server side, synchronisation runs, the Credential Broker that hands short lived leases instead of secrets, and the Webhook Gateway that receives signed provider events.

Resource

Attributes:

Name	Type	Required	Description
connector	string,	yes	Connector that receives the payload of deliver (POST /v1/webhooks/{connector}).
opts	CallOptions,	no	Per call options of deliver; the signature headers are added to them.
payload	unknown,	yes	Payload of deliver, serialized to JSON then signed byte for byte.
signing	{ secret: string; tenant: string; deliveryId?: string },	yes	Signing settings of deliver: secret, tenant and optional delivery id.

WebhooksResource.deliver

async deliver(connector: string, payload: unknown, signing: { secret: string; tenant: string; deliveryId?: string }, opts?: CallOptions)

Receive a provider webhook. Entry point for the provider, without platform authentication. Headers: X-EAI-Tenant (tenant slug, else 400 tenant_required), X-EAI-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>." + raw body>; X-EAI-Timestamp may carry the time), optional X-EAI-Delivery (dedupe id). Steps: 1. The connector must exist, be active and have webhooks enabled (404 connector_not_found). 2. Signature checked with the stored webhook_secret or the manifest secret reference (401 invalid_signature); timestamp within 5 minutes (401 webhook_replay); a delivery already accepted answers 409 webhook_duplicate. 3. The JSON body is screened as untrusted content (prompt injection blocked), then published as connectors.<name>.webhook, which may start triggered runs. Answers 202 with delivery_id, event_id and triggered. Every delivery is recorded and audited as webhook.receive.

Route: /v1/webhooks/{connector} (POST).

Name	Type	Default	Required	Description
connector	string		yes	Name of the connector the provider sends to.
payload	unknown		yes	Raw provider payload; the signature is verified on these exact bytes, whatever the content type.
signing	{ secret: string; tenant: string; deliveryId?: string }		yes	Signing secret, tenant and optional delivery id; a delivery id is generated when missing.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

WebhooksResource.deliveries

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

List the webhook deliveries. Webhook deliveries received, newest first: connector, delivery id, signature validity, status (accepted, rejected, duplicate), reason, SHA-256 of the payload and published event. The payload itself is not stored here.

Route: /v1/webhooks/deliveries (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).

Class ChannelsResource

Channels. Channel Gateway: the entry points where end users talk to agents (web, mobile, email, Slack, Teams, WhatsApp, SMS, voice, API, and the Navin channels Discord, Telegram, Matrix, Mattermost and Signal). An inbound message becomes a session message and starts a run of the channel agent, within size, rate and session limits and with DLP.

Resource

ChannelsResource.create

create(body: Doc, opts?: CallOptions)

Create or update a channel. Applies a Channel manifest (apply_status: created or updated); project (id or slug, default the X-Project header) attaches it to a project, and a channel of another project is never taken over (409 channel_project_conflict). The agent_ref agent must exist (404 agent_not_found); signed_webhook needs auth.secret_ref (422 invalid_manifest). Needs tenant_admin, developer or application_owner. Audited as channel.apply.

Route: /v1/channels (POST).

Name	Type	Default	Required	Description
body	Doc		yes	Channel manifest (kind: Channel, metadata, spec with type, agent, auth, limits, DLP and sessions).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ChannelsResource.delete

delete(name: string, opts?: CallOptions)

Delete a channel. Deletes the channel. Needs tenant_admin. 404 channel_not_found. Audited as channel.delete.

Route: /v1/channels/{name} (DELETE).

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

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

ChannelsResource.get

get(name: string, opts?: CallOptions)

Get a channel. Returns the channel with its manifest, type, agent, status, project and preset. 404 channel_not_found.

Route: /v1/channels/{name} (GET).

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

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

ChannelsResource.inbound

inbound(name: string, body: Doc, opts?: CallOptions)

Post an inbound message. Delivers a message from an end user (202) and returns session_id, session_created, message_id, run_id (or run_skipped when the agent is not active) and the DLP result. Needs tenant_admin, developer or agent. Steps: 1. The channel must be active (409 channel_disabled); a signed_webhook channel checks X-EAI-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>." + raw body>, 5 minute window; 401 invalid_signature). 2. The policy channel.inbound is evaluated; size (413 message_too_large) and rate per user (429 rate_limited) are checked. 3. Inbound DLP runs (default detect; block answers 403 dlp_blocked, mask stores the masked text). 4. The open session of the user and conversation is reused, or a new one opened (429 too_many_sessions, 409 session_closed past max_session_minutes). 5. The message is added and a run of the channel agent starts with trigger channel.

Route: /v1/channels/{name}/inbound (POST).

Name	Type	Default	Required	Description
name	string		yes	Name of the channel.
body	Doc		yes	JSON message: text (1 to 1000000 characters, required), user (external user id, up to 300 characters; default the caller), conversation_id (up to 300 characters; default the user) and metadata (kept with the message). The raw bytes are used for the signature check.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

ChannelsResource.list

list(params?: ListParams & { project?: string }, opts?: CallOptions)

List the channels. Channels of the tenant in name order; project (id or slug) keeps the channels of that project only (404 project_not_found). One page only.

Route: /v1/channels (GET).

Name	Type	Default	Required	Description
params	ListParams & { project?: 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).

ChannelsResource.sessions

sessions(name: string, params?: ListParams, opts?: CallOptions)

List the sessions of a channel. Sessions opened on the channel, most recently updated first, at most 500.

Route: /v1/channels/{name}/sessions (GET).

Name	Type	Default	Required	Description
name	string		yes	Name of the channel.
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).

ChannelsResource.update

update(name: string, body: Doc, opts?: CallOptions)

Update a channel. Changes the status (active or disabled; a disabled channel refuses inbound messages) or the owner. Needs tenant_admin, developer or application_owner. Audited as channel.update.

Route: /v1/channels/{name} (PATCH).

Name	Type	Default	Required	Description
name	string		yes	Name of the channel.
body	Doc		yes	Fields to change; the omitted ones are kept.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Type alias NavinLibraryKind

Kind of Navin library item: skills, plugins, commands, agents, mcp-presets or channels.

Definition: "skills" \| "plugins" \| "commands" \| "agents" \| "mcp-presets" \| "channels".

Class NavinLibraryResource

Navin library vendored with the platform, activated per project, and the rules of a project.

Resource

NavinLibraryResource.activate

activate(projectId: string, body: { kind: "skill" | "plugin" | "command" | "agent"; name: string }, opts?: CallOptions)

Activate a library item. Activates a skill, a plugin (with its skills, commands and agents), a command or an agent for the project (201). A skill is registered in the Skill Registry, verified by its library digest; a skill name already used by a skill not from the library answers 409 navin_skill_name_taken. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. 422 navin_library_kind_not_activable; 404 navin_library_item_not_found. Audited as navin_library.activate.

Route: /v1/projects/{project_id}/navin-library/activations (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
body	{ kind: "skill" | "plugin" | "command" | "agent"; name: string }		yes	Kind and name of the item to activate.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.deactivate

deactivate(projectId: string, activationId: string, opts?: CallOptions)

Deactivate a library item. Removes an activation from the project; a plugin takes the skills, commands and agents it brought with it. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. 404 navin_library_activation_not_found. Audited as navin_library.deactivate.

Route: /v1/projects/{project_id}/navin-library/activations/{activation_id} (DELETE).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
activationId	string		yes	Identifier (UUID) of the activation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.deleteRule

deleteRule(projectId: string, name: string, opts?: CallOptions)

Delete a project rule. Deletes the rule; runs of the project no longer receive it. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. 404 rule_not_found. Audited as project.rule.delete.

Route: /v1/projects/{project_id}/rules/{name} (DELETE).

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

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

NavinLibraryResource.importRules

importRules(projectId: string, files: { path: string; content: string }[], opts?: CallOptions)

Import the rule files of a repository. Imports the rule files of a repository (.navin/rules, .cursor/rules/*.mdc with their frontmatter, .cursorrules, .clinerules, .windsurfrules, .github/copilot-instructions.md); each recognised file creates or replaces a rule. Other files are reported in skipped with a reason (not_a_rule_file, empty, too_large). At most 200 files (400 invalid_request). Needs tenant_admin, developer or application_owner and the ReBAC relation editor.

Route: /v1/projects/{project_id}/rules/import (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
files	{ path: string; content: string }[]		yes	Files to import (1 to 200).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.installChannel

installChannel(projectId: string, name: string, body: { name?: string; agent_ref?: string; settings?: Doc; secret_refs?: Record<string, string>; auth?: Doc; limits?: Record<string, number>; dlp?: Record<string, string> }, opts?: CallOptions)

Install a channel from the library. Creates a channel of the project from a Navin channel adapter (201). The setup contract of the adapter is checked: unknown, secret or read-only fields in settings and non secret fields in secret_refs answer 422 channel_field_invalid, a wrong value kind also, missing requirements 422 channel_field_missing; secrets are openbao:// or env:// references only (422 channel_secret_ref_required). Defaults: auth api_key, limits 65536 bytes per message and 60 per minute, DLP detect inbound and mask outbound. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. Audited as navin_library.channel_install.

Route: /v1/projects/{project_id}/navin-library/channels/{name}/install (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
name	string		yes	Name of the Navin channel adapter.
body	{ name?: string; agent_ref?: string; settings?: Doc; secret_refs?: Record<string, string>; auth?: Doc; limits?: Record<string, number>; dlp?: Record<string, string> }		yes	Channel name, agent, settings, secret references, authentication, limits and DLP.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.installMcpPreset

installMcpPreset(projectId: string, name: string, body: { name?: string; url?: string; transport?: "streamable_http" | "sse"; values?: Record<string, string | number | boolean>; credential_refs?: Record<string, string>; allowed_tools?: string[] }, opts?: CallOptions)

Install an MCP server from a preset. Registers an MCP server of the project in the MCP gateway from a Navin preset (201), over streamable HTTP or SSE. A stdio preset runs where its command runs (the MCP page of the Navin Manager): give its HTTP endpoint in url; its environment and argument fields are returned in bridge_fields. Errors: 409 mcp_preset_not_installable, 409 mcp_preset_needs_endpoint, 422 mcp_preset_field_unknown, 422 mcp_preset_field_missing, 422 mcp_preset_secret_ref_required (a secret field must be an openbao:// or env:// reference), 422 mcp_preset_unsupported. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. Audited as navin_library.mcp_install.

Route: /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
name	string		yes	Name of the MCP preset.
body	{ name?: string; url?: string; transport?: "streamable_http" | "sse"; values?: Record<string, string | number | boolean>; credential_refs?: Record<string, string>; allowed_tools?: string[] }		yes	Server name, endpoint, transport, preset fields, secret references and allowed tools.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.item

item(kind: NavinLibraryKind, name: string, opts?: CallOptions)

Get a library item. One item with its content (SKILL.md and files of a skill, plugin.json and README of a plugin, Markdown of a command or an agent, full MCP preset or channel contract). 404 navin_library_item_not_found.

Route: /v1/navin-library/{kind}/{name} (GET).

Name	Type	Default	Required	Description
kind	NavinLibraryKind		yes	Kind of item: skills, plugins, commands, agents, mcp-presets or channels.
name	string		yes	Name of the item.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.items

items(kind: NavinLibraryKind, query?: { q?: string; category?: string }, opts?: CallOptions)

List the library items of a kind. Items of one kind: skills, plugins, commands, agents, mcp-presets or channels (q searches name and description, category filters skills, plugins and MCP presets). An unknown kind answers 404 navin_library_kind_unknown.

Route: /v1/navin-library/{kind} (GET).

Name	Type	Default	Required	Description
kind	NavinLibraryKind		yes	Kind of item: skills, plugins, commands, agents, mcp-presets or channels.
query	{ q?: string; category?: string }		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).

NavinLibraryResource.project

project(projectId: string, opts?: CallOptions)

Get what a project uses from the library. Library version, activations of the project with counts per kind, and the MCP servers and channels of the project (with the preset they come from). Needs the ReBAC relation viewer on the project.

Route: /v1/projects/{project_id}/navin-library (GET).

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

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

NavinLibraryResource.putRule

putRule(projectId: string, name: string, body: { content: string; mode?: "always" | "conditional"; description?: string; globs?: string[]; source?: "navin" | "cursor" | "cursor_legacy" | "cline" | "windsurf" | "copilot" }, opts?: CallOptions)

Create or replace a project rule. Creates (201) or replaces (200) a rule of the project. The name has 1 to 64 letters, digits, ., _ or - (a .md suffix is dropped, readme is refused; 422 rule_name_invalid). Empty content answers 422 rule_empty, more than 64 KiB 413 rule_too_large; a conditional rule needs globs or a description (422 rule_scope_required). Needs tenant_admin, developer or application_owner and the ReBAC relation editor. Audited as project.rule.put.

Route: /v1/projects/{project_id}/rules/{name} (PUT).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
name	string		yes	Name of the rule.
body	{ content: string; mode?: "always" | "conditional"; description?: string; globs?: string[]; source?: "navin" | "cursor" | "cursor_legacy" | "cline" | "windsurf" | "copilot" }		yes	Content, mode, description, globs and source of the rule.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

NavinLibraryResource.rules

rules(projectId: string, opts?: CallOptions)

List the project rules. Rules of the project by mode then name, each with source, source path, description, globs, content, digest and size in bytes. Needs the ReBAC relation viewer.

Route: /v1/projects/{project_id}/rules (GET).

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

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

NavinLibraryResource.rulesPrompt

rulesPrompt(projectId: string, opts?: CallOptions)

Get the rules prompt section. The prompt section every run of the project receives: always on rules inlined (each clipped at 8000 characters), conditional ones listed with their description and globs. Returns prompt, the always and conditional counts and the digest of the text (empty when the project has no rule). Needs the ReBAC relation viewer.

Route: /v1/projects/{project_id}/rules/prompt (GET).

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

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

NavinLibraryResource.summary

summary(opts?: CallOptions)

Get the library summary. Version of the vendored navin package, counts per kind and the rule files read from a repository. 503 navin_library_unavailable when the catalogue is not packaged.

Route: /v1/navin-library (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).

Type alias McpInstanceStatus

State of an MCP Runtime instance: provisioning, ready, failed, terminating or terminated.

Definition: "provisioning" \| "ready" \| "failed" \| "terminating" \| "terminated".

Class McpRuntimeResource

MCP Runtime: isolated MCP instances of the caller in a project, on the ToolHive Kubernetes Operator (ADR-0167).

Resource

McpRuntimeResource.createInstance

createInstance(projectId: string, body: { template: string; name?: string; params?: Record<string, string | number | string[]>; credential_ref?: string; agents?: string[]; allowed_tools?: string[]; idle_timeout_seconds?: number }, opts?: CallOptions)

Start an MCP instance. Starts an isolated MCP instance of the caller in the project (202): ToolHive MCPServer of its own, credentials of its own, ready when ToolHive reports it Ready (GET the instance to follow it). Needs tenant_admin, developer or application_owner and the ReBAC relation editor on the project. Checks: the MCP Runtime is enabled (409 mcp_runtime_disabled); the template, its hosts and database roles are allowed by the project policy (403 mcp_template_not_allowed, mcp_host_not_allowed, mcp_database_role_not_allowed); a template with personal credentials needs credential_ref (422 mcp_credential_required); agents, tools and name are valid (422); quotas per user and per project (409 mcp_instance_quota); no other instance of the caller with the same name (409 mcp_instance_exists). A failed provisioning destroys the instance and returns the error. Audited as mcp.instance.create.

Route: /v1/projects/{project_id}/mcp/instances (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
body	{ template: string; name?: string; params?: Record<string, string | number | string[]>; credential_ref?: string; agents?: string[]; allowed_tools?: string[]; idle_timeout_seconds?: number }		yes	Template, name, parameters, personal credential, agents, allowed tools and idle time.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

McpRuntimeResource.destroyInstance

destroyInstance(projectId: string, instanceId: string, opts?: CallOptions)

Destroy an MCP instance. Destroys the instance at the end of the task: credentials revoked, resources deleted, gateway entry disabled, journal kept. Allowed for its owner, or tenant_admin and security_officer (recorded as an administrator destruction). Needs the ReBAC relation viewer on the project. Returns the instance and its journal. 404 mcp_instance_not_found.

Route: /v1/projects/{project_id}/mcp/instances/{instance_id} (DELETE).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
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).

McpRuntimeResource.instance

instance(projectId: string, instanceId: string, opts?: CallOptions)

Get an MCP instance. The instance (its state read again from ToolHive while it is provisioning or ready) and its lifecycle journal in events. credential_active tells whether credentials are currently issued. Visible to its owner, tenant_admin and security_officer; needs the ReBAC relation viewer on the project. 404 mcp_instance_not_found.

Route: /v1/projects/{project_id}/mcp/instances/{instance_id} (GET).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
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).

McpRuntimeResource.instances

instances(projectId: string, query?: { status?: McpInstanceStatus }, opts?: CallOptions)

List the MCP instances of a project. Returns enabled (whether the MCP Runtime runs on this platform), the project policy (defaults when not configured), the catalogue state, the templates and the instances, newest first, at most 500: its own for a user, every one for tenant_admin and security_officer. Needs the ReBAC relation viewer on the project.

Route: /v1/projects/{project_id}/mcp/instances (GET).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
query	{ status?: McpInstanceStatus }		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).

McpRuntimeResource.jwks

jwks(opts?: CallOptions)

Get the MCP runtime verification keys. Public verification keys of the tokens the MCP Gateway gives the ToolHive proxies (no secret: public keys only, as any OIDC JWKS). Read without authentication by the MCPOIDCConfig eai-mcp-runtime of every project namespace. 503 context_authority_unavailable when the key registry cannot be read.

Route: /v1/mcp/runtime/jwks (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).

McpRuntimeResource.putPolicy

putPolicy(projectId: string, body: { allowed_templates?: string[]; allowed_hosts?: string[]; allowed_database_roles?: string[]; idle_timeout_seconds?: number; max_lifetime_seconds?: number; max_instances_per_user?: number; max_instances_per_project?: number }, opts?: CallOptions)

Set the MCP runtime policy of a project. Replaces the policy of the MCP Runtime of the project: templates, hosts, database roles, idle time, lifetime and quotas. Unknown templates, invalid host patterns or role names answer 422 mcp_policy_invalid. New and woken instances follow it. Needs tenant_admin and the ReBAC relation editor on the project. Audited as mcp.runtime.policy.

Route: /v1/projects/{project_id}/mcp/policy (PUT).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
body	{ allowed_templates?: string[]; allowed_hosts?: string[]; allowed_database_roles?: string[]; idle_timeout_seconds?: number; max_lifetime_seconds?: number; max_instances_per_user?: number; max_instances_per_project?: number }		yes	The complete policy; omitted fields take their default.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

McpRuntimeResource.startInstance

startInstance(projectId: string, instanceId: string, opts?: CallOptions)

Start a sleeping or failed instance. Starts a sleeping or failed instance again now (failure count reset): template and project policy checked again, new generation and credentials; ready when ToolHive reports it Ready (GET the instance to follow it). 409 mcp_instance_busy while another lifecycle operation runs. Allowed for its owner, tenant_admin and security_officer; needs the ReBAC relation viewer on the project. Returns the instance and its journal (202).

Route: /v1/projects/{project_id}/mcp/instances/{instance_id}/start (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
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).

McpRuntimeResource.stopInstance

stopInstance(projectId: string, instanceId: string, opts?: CallOptions)

Put an MCP instance to sleep. Stops the instance now (credentials revoked, resources deleted): it sleeps, its gateway entry stays and its next call recreates it. Allowed for its owner, tenant_admin and security_officer; needs the ReBAC relation viewer on the project. Returns the instance and its journal.

Route: /v1/projects/{project_id}/mcp/instances/{instance_id}/stop (POST).

Name	Type	Default	Required	Description
projectId	string		yes	Identifier (UUID) or slug of the project.
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).

Type alias FileScanStatus

State of a scanned file: quarantined, released or blocked.

Definition: "quarantined" \| "released" \| "blocked".

Type alias FileScanVerdict

Verdict of a scan: clean, malware, suspicious, unscannable, scan_error or policy_violation.

Definition: "clean" \| "malware" \| "suspicious" \| "unscannable" \| "scan_error" \| "policy_violation".

Type alias FileScanSource

Source of a scanned file: knowledge, media, multimodal, transcription, connector, channel or api.

Definition: "knowledge" \| "media" \| "multimodal" \| "transcription" \| "connector" \| "channel" \| "api".

Interface FileScanRecord

Record of one file analysis (ClamAV and YARA-X, then the built-in checks).

Fields:

Name	Type	Required	Description
id	string	yes	Id of the scan record.
status	FileScanStatus	yes	State of the file: quarantined, released or blocked.
verdict	FileScanVerdict | null	yes	Verdict of the scan, null while it runs.
reasons	string[]	yes	Reasons behind the verdict.
source	FileScanSource	yes	Where the file came from, for example knowledge, media or api.
source_ref	string | null	no	Reference of the file in its source.
filename	string | null	no	Name of the analysed file, when it was given.
mime_type	string | null	no	Media type of the content, for example application/pdf or image/png.
detected_type	string | null	no	File type detected from the content.
size_bytes	number	yes	Size of the file in bytes.
sha256	string	yes	SHA-256 digest of the file.
engines	Doc	yes	Results of each scan engine.
sample_retained	boolean	yes	Whether a sample of the file is kept.
rescan_of	string | null	no	Id of the scan this one repeats, for a rescan.
created_by	string | null	no	Principal that sent the file.
created_at	string	yes	Time the record was created.
scanned_at	string | null	no	Time the scan ended.
expires_at	string | null	no	Date and time (ISO 8601, UTC) after which the item is no longer valid.

Interface FileSecurityPolicyUpdate

Editable fields of the tenant policy (the locked rules can never be changed).

Fields:

Name	Type	Required	Description
max_file_bytes	number	no	Largest file accepted, in bytes: 1024 to the platform ceiling EAI_FILE_SCAN_MAX_BYTES (the default). A larger file is blocked as a policy violation without reaching the engines.
allowed_types	string[]	no	Detected file types accepted, among the known types (text, html, pdf, ooxml, ole, odf, zip, gzip, tar, 7z, rar, png, jpeg, gif, webp, tiff, wav, mp3, ogg, flac, mp4, webm, avi, executable, binary). Default: every known type except executable.
allow_archives	boolean	no	Whether archives (zip, gzip, tar, 7z, rar) are accepted; default true.
block_office_macros	boolean	no	Whether Office documents with macros are blocked; default true. When false, the macro is only reported in the reasons.
block_type_mismatch	boolean	no	Whether a file whose detected type contradicts its declared media type is blocked; default true.
retain_samples	boolean	no	Whether an encrypted sample of each blocked file is kept for a later rescan; default true.
quarantine_retention_days	number	no	Days a sample is kept before the retention job deletes it, 1 to 365, default 30.
max_signature_age_hours	number	no	Maximum age of the ClamAV signatures in hours, 1 to 720, default 48. Older or undated signatures are stale.
stale_signatures	"warn" | "block"	no	What stale ClamAV signatures do to a scan: warn (default) only adds a reason, block blocks the file with verdict scan_error.

Interface FileScanInput

Input of FileSecurityResource.scan: base64 content or bytes, file name and MIME type.

Fields:

Name	Type	Required	Description
contentBase64	string	no	Base64 content; or data (bytes), encoded here.
data	Uint8Array | ArrayBuffer	no	Bytes of the file, encoded in base64 by the SDK (or give contentBase64).
filename	string	no	Name of the file to analyse, sent as filename.
mimeType	string	no	Media type of the content, for example application/pdf or image/png.

Class FileSecurityResource

/v1/file-security: engine status, tenant policy, explicit scans, rescans, sample purge and stats.

Resource

FileSecurityResource.getScan

getScan(scanId: string, opts?: CallOptions): Promise<FileScanRecord>

Get a scan record. One scan record: status, verdict, reasons, source and its reference, file name, declared and detected type, size, SHA-256, answer of each engine, whether a sample is kept, the scan it rescans, creator and dates (creation, scan, sample expiry). Requires a tenant principal; a record of someone else is visible only to tenant_admin, security_officer and auditor (404 not_found otherwise).

Route: /v1/file-security/scans/{scan_id} (GET).

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

Returns: Promise<FileScanRecord>. A FileScanRecord: Record of one file analysis (ClamAV and YARA-X, then the built-in checks).

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

FileSecurityResource.listScans

listScans(params?: ListParams & { status?: FileScanStatus; verdict?: FileScanVerdict; source?: FileScanSource }, opts?: CallOptions)

List the scan records. Scan records of the tenant, newest first; a principal without a reader role (tenant_admin, security_officer, auditor) only sees its own scans. Requires a tenant principal. An unknown status, verdict or source answers 400 invalid_request; a malformed cursor 400 invalid_cursor.

Route: /v1/file-security/scans (GET).

Name	Type	Default	Required	Description
params	ListParams & { status?: FileScanStatus; verdict?: FileScanVerdict; source?: FileScanSource }		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).

FileSecurityResource.policy

policy(opts?: CallOptions)

Read the file security policy. Effective policy of the tenant: the locked rules, every editable rule (stored values over the defaults, the size never above the platform ceiling EAI_FILE_SCAN_MAX_BYTES), the known file types, and when and by whom it was last changed. Requires a tenant principal with tenant_admin, security_officer or auditor (403 forbidden).

Route: /v1/file-security/policy (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).

FileSecurityResource.purgeSample

purgeSample(scanId: string, opts?: CallOptions)

Purge the sample of a blocked file. Deletes the encrypted sample of a blocked file now, without waiting for the end of its retention, and answers sample_retained: false. The purge is audited (file_security.sample.purge) with the SHA-256 of the file. Requires a tenant principal with security_officer or tenant_admin (403 forbidden). A scan that is unknown or not visible to the caller answers 404 not_found.

Route: /v1/file-security/scans/{scan_id}/sample (DELETE).

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

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

FileSecurityResource.rescan

rescan(scanId: string, opts?: CallOptions): Promise<FileScanRecord>

Rescan the sample of a blocked file. Scans the retained sample of a blocked file again, for example after a signature update, and answers 201 with a new record whose rescan_of names the original scan. The original upload is never released: a clean result only informs. Requires a tenant principal with security_officer or tenant_admin (403 forbidden). Without a retained sample: 409 file_sample_unavailable; unknown or invisible scan: 404 not_found.

Route: /v1/file-security/scans/{scan_id}/rescan (POST).

Name	Type	Default	Required	Description
scanId	string		yes	Identifier of the blocked scan record whose sample is scanned again.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Returns: Promise<FileScanRecord>. A FileScanRecord: Record of one file analysis (ClamAV and YARA-X, then the built-in checks).

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

FileSecurityResource.scan

scan(input: FileScanInput, opts?: CallOptions): Promise<FileScanRecord>

Scan a file without ingesting it. Scans a file without ingesting it and answers 201 with the record, released or blocked (a blocked file is not an error here). Any tenant principal may call it (403 tenant_required otherwise).

Route: /v1/file-security/scans (POST).

Name	Type	Default	Required	Description
input	FileScanInput		yes	File to scan: contentBase64 or data, plus optional filename and mimeType; without content a TypeError is thrown.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Returns: Promise<FileScanRecord>. A FileScanRecord: Record of one file analysis (ClamAV and YARA-X, then the built-in checks).

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

FileSecurityResource.stats

stats(params?: { window_hours?: number }, opts?: CallOptions)

Read the scan statistics. Number of scans over the last window_hours hours, by status, by verdict and by source, with the time of the last blocked file. Readers (tenant_admin, security_officer, auditor) count every scan of the tenant, anyone else only its own. Requires a tenant principal. A window outside 1 to 8784 hours answers 400 invalid_request.

Route: /v1/file-security/stats (GET).

Name	Type	Default	Required	Description
params	{ window_hours?: number }		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).

FileSecurityResource.status

status(opts?: CallOptions)

Read the scan engines status. Mode (enforce or dev), readiness, pipeline and every ClamAV gateway and YARA-X worker, probed live: version, signature version, publication and age with a stale flag against the policy, rules version, hash, count and load time, latency. The instance is ready when each engine has at least one healthy endpoint (in enforce mode, or when it is configured). Requires tenant_admin, security_officer or auditor (403 forbidden).

Route: /v1/file-security/status (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).

FileSecurityResource.updatePolicy

updatePolicy(body: FileSecurityPolicyUpdate, opts?: CallOptions)

Change the file security policy. Changes the editable rules given in the body; the other rules keep their value. Sizes may only be tighter than the platform ceiling, and the locked rules never change (422 file_security_rule_locked). An unknown field, an unknown type or a value out of bounds answers 422 invalid_request with the field and the reason. Requires a tenant principal with security_officer or tenant_admin (403 forbidden). The change is audited (file_security.policy.update) with the values before and after; the answer is the new effective policy.

Route: /v1/file-security/policy (PUT).

Name	Type	Default	Required	Description
body	FileSecurityPolicyUpdate		yes	Editable rules to change; omitted fields keep their value.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Functions

signWebhook

async signWebhook(secret: string, rawBody: string, options: { tenant: string; deliveryId?: string; timestamp?: number }): Promise<WebhookHeaders>

Signs a raw webhook body for clients that push events to the platform: X-EAI-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, plus X-EAI-Tenant and the optional X-EAI-Delivery dedupe id. Uses WebCrypto (Node 18+, browsers).

Name	Type	Default	Required	Description
secret	string		yes	Shared HMAC secret of the webhook.
rawBody	string		yes	Raw body to sign, exactly as sent.
options	{ tenant: string; deliveryId?: string; timestamp?: number }		yes	Per call options (idempotency key, traceparent, headers, abort signal).

Returns: Promise<WebhookHeaders>. The headers to send; throws when WebCrypto is missing.

Raises: Error.

verifyWebhook

async verifyWebhook(secret: string, rawBody: string, header: string | null | undefined, options: { toleranceSeconds?: number; now?: number } = {}): Promise<boolean>

Verifies X-EAI-Signature: t=<unix>,v1=<hex> over "<t>.<raw body>" with a constant time comparison and a timestamp tolerance (default 300 s). Returns false on any mismatch or malformed header.

Name	Type	Default	Required	Description
secret	string		yes	Shared HMAC secret of the webhook.
rawBody	string		yes	Raw body received, before any parsing.
header	string | null | undefined		yes	Value of the received X-EAI-Signature header.
options	{ toleranceSeconds?: number; now?: number }	{}	no	Per call options (idempotency key, traceparent, headers, abort signal).

Returns: Promise<boolean>. True when one v1 signature matches and the timestamp is within the tolerance.