resources/tools.ts

Source : sdks/typescript/packages/sdk/src/resources/tools.ts. Retour à l'index de la référence du SDK TypeScript.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Classe ToolsResource

Registre des outils (/v1/tools) et invocation par la Tool Gateway, qui applique côté serveur portées, politique, DLP, approbation et coût.

Resource

Attributs :

Nom	Type	Requis	Description
body	{ arguments?: Doc; run_id?: string; agent_id?: string; approval_id?: string; purpose?: string; data_classification?: "public" | "internal" | "confidential" | "restricted" | "secret" } & Doc,	oui	Corps d'invoke : arguments de l'outil, run, agent, approbation, finalité et classification des données.
name	string,	oui	Nom de l'outil appelé par invoke.
opts	CallOptions) {	non	Options par appel d'invoke.

ToolsResource.create

create(body: Doc, opts?: CallOptions)

Enregistrer un outil. Applique un manifeste Tool : crée ou met à jour l'outil (apply_status : created, updated ou unchanged). Contrôles : schémas JSON d'entrée et de sortie valides, un point d'accès http demande une URL http(s) permise par la politique de sortie réseau, un point d'accès mcp demande mcp_server, un gestionnaire builtin doit être echo ou time.now, le niveau de risque unacceptable est refusé (422 invalid_manifest). Demande tenant_admin, developer ou application_owner ; l'appelant devient propriétaire ReBAC. Audité sous tool.apply.

Route : /v1/tools (POST).

Nom	Type	Défaut	Requis	Description
body	Doc		oui	Manifeste Tool (kind: Tool, metadata, spec avec description, action, schéma d'entrée, point d'accès, classification de données et options).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.delete

delete(name: string, opts?: CallOptions)

Supprimer un outil. Retire l'outil du registre. Demande tenant_admin et la relation ReBAC owner. 404 tool_not_found. Audité sous tool.delete.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom de l'outil.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.discover

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

Lister les outils. Outils du tenant dans l'ordre des noms, éventuellement d'un seul statut. Une seule page.

Route : /v1/tools (GET).

Nom	Type	Défaut	Requis	Description
query	{ status?: string }	{ status: "approved" }	non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.get

get(name: string, opts?: CallOptions)

Lire un outil. Renvoie l'outil avec son manifeste, son niveau de risque, son propriétaire et son statut. Demande la relation ReBAC viewer. 404 tool_not_found.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom de l'outil.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.invocations

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

Lister les invocations d'outils. Invocations enregistrées par la Tool Gateway, de la plus récente à la plus ancienne, paginées avec cursor : outil et version, acteur, run, agent, statut, décision, approbation, arguments et résultat expurgés, détections DLP, statut HTTP, erreur et durée. Les arguments et résultats ne sont conservés qu'expurgés.

Route : /v1/tools/invocations (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

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)

Invoquer un outil via la passerelle. Exécute la chaîne de la passerelle décrite dans l'introduction du tag et renvoie l'invocation : status, result masqué, error, duration_ms, decision_id, détections DLP, événement d'usage et coût. Demande tenant_admin, developer ou agent et la relation ReBAC can_invoke. Réponses : 200 une fois exécuté (aussi quand l'amont a échoué, voir status et error) ; 202 pending_approval avec approval_id quand une validation humaine est requise (rappelez avec l'approval_id approuvé et les mêmes arguments) ; 202 pour un outil sandbox, avec l'identifiant de l'exécution en sandbox. Erreurs : 403 tool_blocked, insufficient_scope, tool_not_granted, classification_exceeded, policy_denied, dlp_blocked ; 422 invalid_arguments ; 409 approval_consumed (une approbation sert un seul appel réussi) ; 429 rate_limited avec Retry-After: 60 ou quota_exceeded.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom de l'outil.
body	{ arguments?: Doc; run_id?: string; agent_id?: string; approval_id?: string; purpose?: string; data_classification?: "public" | "internal" | "confidential" | "restricted" | "secret" } & Doc		oui	Arguments de l'appel et son contexte (run, agent, approbation, finalité, classification).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.list

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

Lister les outils. Outils du tenant dans l'ordre des noms, éventuellement d'un seul statut. Une seule page.

Route : /v1/tools (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.update

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

Modifier un outil. Modifie le propriétaire, la description ou le statut. Un changement de statut demande tenant_admin ou security_officer, les autres champs tenant_admin, developer ou application_owner ; la relation ReBAC editor est vérifiée. approved passe par une promotion (202 avec approval_id) ; les autres statuts s'appliquent aussitôt (200). Audité sous tool.update.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom de l'outil.
body	Doc		oui	Champs à modifier ; ceux omis sont conservés.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ToolsResource.validate

validate(manifest: Doc, opts?: CallOptions)

Valider un document avec un contrat. Valide le corps avec le contrat, formats compris, sans rien enregistrer. La réponse donne contract, valid et errors, chacune avec le path JSON de la valeur fautive et un message. Ouvert à tout appelant authentifié. Un contrat inconnu répond 404 unknown_contract.

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

Nom	Type	Défaut	Requis	Description
manifest	Doc		oui	Tool Manifest à valider sur le serveur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Interface JsonRpcResponse

Réponse JSON-RPC 2.0 de la passerelle MCP : un résultat ou une erreur.

Champs :

Nom	Type	Requis	Description
jsonrpc	"2.0"	oui	Toujours 2.0.
id	number | string | null	oui	Identifiant de la requête à laquelle correspond cette réponse.
result	T	non	Résultat de l'appel.
error	{ code: number; message: string; data?: unknown }	non	Erreur RPC : code, message et données ; rpc lève mcp_error lorsqu'elle est présente.

Classe McpResource

Passerelle MCP. Registre des serveurs MCP amont (Model Context Protocol) et MCP Gateway, un proxy JSON-RPC 2.0 qui applique les contrôles de la plateforme à chaque appel : isolation par projet, appelants permis, listes d'autorisation d'outils et de ressources, scopes, DLP, politique, quota, contrôle d'injection de prompt, comptage et audit.

Resource

McpResource.callTool

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

Appelle un outil d'un serveur MCP (JSON-RPC tools/call) via la passerelle MCP.

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
name	string		oui	Nom de l'outil sur le serveur MCP.
args	Doc	{}	non	Arguments de l'outil (objet vide par défaut).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

McpResource.catalog

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

Lire le catalogue des outils MCP. Catalogue : outils, schémas d'entrée et de sortie, versions, scopes et statut d'approbation (approved, pending_approval, rejected), pour les seuls serveurs visibles par la requête, comme GET /v1/mcp/servers.

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

Nom	Type	Défaut	Requis	Description
query	{ server?: string }	{}	non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.connect

connect(serverId: string, opts?: CallOptions)

JSON-RPC initialize via la passerelle MCP : les informations du serveur (une erreur RPC lève une exception).

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

McpResource.deleteServer

deleteServer(id: string, opts?: CallOptions)

Supprimer un serveur MCP. Retire le serveur du registre. Demande tenant_admin, la relation ReBAC owner et l'accès au projet du serveur. 404 mcp_server_not_found. Audité sous mcp.server.delete.

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

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) ou nom du serveur MCP.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.discover

discover(serverId: string, opts?: CallOptions)

Découvrir les outils d'un serveur MCP. Découverte par le protocole MCP (initialize, tools/list) : chaque schéma d'outil nouveau ou modifié devient une version du catalogue en attente d'approbation (mcp_tool_version, approbateurs tenant_admin ou security_officer). Renvoie les versions créées avec leurs identifiants d'approbation. Demande tenant_admin, developer ou application_owner, la relation ReBAC editor et l'accès au projet du serveur.

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

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant (UUID) ou nom du serveur MCP.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

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 via la passerelle MCP, avec le protocole 2024-11-05 et les informations du client SDK par défaut.

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
params	Doc	{ protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "@enterprise-ai/sdk", version: "1.0.0" } }	non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

McpResource.listPrompts

listPrompts(serverId: string, opts?: CallOptions)

Liste les prompts d'un serveur MCP (JSON-RPC prompts/list).

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

McpResource.listResources

listResources(serverId: string, opts?: CallOptions)

Liste les ressources d'un serveur MCP (JSON-RPC resources/list).

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

McpResource.listServers

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

Lister les serveurs MCP. Serveurs visibles par la requête : project (identifiant ou slug) ne garde que les serveurs de ce projet ; une requête faite dans un projet (en-tête X-Project ou clé d'API liée à un projet) voit les serveurs de son projet et ceux partagés par le tenant, jamais ceux d'un autre projet (403 mcp_project_forbidden). Les secrets amont ne sont jamais renvoyés, seulement leurs références.

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

Nom	Type	Défaut	Requis	Description
params	ListParams & { project?: string }		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.listTools

listTools(serverId: string, opts?: CallOptions)

Liste les outils d'un serveur MCP (JSON-RPC tools/list).

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

McpResource.readResource

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

Lit une ressource d'un serveur MCP (JSON-RPC resources/read).

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant du serveur MCP enregistré.
uri	string		oui	URI de la ressource à lire.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

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)

Enregistrer un serveur MCP. Enregistre un serveur amont (201). L'URL doit être http(s) sur un hôte interne permis par la politique de sortie MCP (403 mcp_online_forbidden sinon) ; bearer, api_key et query_param demandent un credential_ref openbao:// ou env://, query_param demande param, connector demande connector (400 invalid_request). Un nom déjà utilisé répond 409 conflict. Le projet (par défaut X-Project) doit être celui de la requête (403 mcp_project_forbidden). Demande tenant_admin, developer ou application_owner ; l'appelant devient propriétaire ReBAC. Audité sous mcp.server.create.

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

Nom	Type	Défaut	Requis	Description
body	{ name: string; url: string; transport?: "sse" | "streamable_http"; auth?: Doc; owner?: string; allowed_tools?: string[]; allowed_resources?: string[] } & Doc		oui	Nom, URL, transport, authentification amont, listes d'autorisation, propriétaire et projet.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.serverTools

serverTools(id: string, opts?: CallOptions)

Lister les outils d'un serveur MCP. Appelle tools/list sur le serveur via la passerelle et renvoie les outils permis par allowed_tools. Demande la relation ReBAC can_invoke et l'accès au projet du serveur. Une erreur amont répond 502 upstream_error.

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

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) ou nom du serveur MCP.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.setAccess

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

Définir qui peut appeler un serveur MCP. Contrôle d'accès de la MCP Gateway : quels utilisateurs et agents peuvent appeler ce serveur ; une liste vide laisse tout membre de son projet l'appeler. Les identifiants de principaux sont faits de lettres, chiffres et :._@/- (128 caractères au plus, 400 invalid_request). L'accès d'une instance hébergée est géré par le runtime MCP (409 mcp_instance_access_managed). Demande tenant_admin, developer ou application_owner et l'accès au projet du serveur. Audité sous mcp.server.access.

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

Nom	Type	Défaut	Requis	Description
serverId	string		oui	Identifiant (UUID) ou nom du serveur MCP.
principals	string[]		oui	Utilisateurs et agents (identifiants de principaux, 200 au plus) autorisés à appeler le serveur ; vide : tout membre de son projet.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.setServerStatus

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

Activer ou désactiver un serveur MCP. active passe par une promotion : une approbation est ouverte et la réponse est 202 avec approval_id. disabled s'applique aussitôt (tout appel de passerelle est alors refusé) et est audité sous mcp.server.status. Demande tenant_admin ou security_officer, la relation ReBAC editor et l'accès au projet du serveur.

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

Nom	Type	Défaut	Requis	Description
id	string		oui	Identifiant (UUID) ou nom du serveur MCP.
body	{ status: string; reason?: string }		oui	Statut visé et raison.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpResource.syncHosted

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

Publier les serveurs MCP hébergés par le Navin Manager. Publie les serveurs MCP hébergés par le Navin Manager (service mcp-host) dans leur projet : jeton conservé dans le Credential Broker, serveur du projet créé ou mis à jour, serveurs qui ne sont plus hébergés désactivés. project (identifiant ou slug, par défaut le projet de la requête) limite la synchronisation à un projet ; un projet différent de celui de la requête répond 403 mcp_project_forbidden. Demande tenant_admin et un tenant (403 tenant_required).

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

Nom	Type	Défaut	Requis	Description
query	{ project?: string }		non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe SkillsResource

Skills. Skill Registry et Skill Loader. Un skill est un ensemble d'instructions signé et versionné (en ligne, ou artefact Git ou OCI) avec les permissions dont il a besoin ; les agents chargent les skills accordés dans leur manifeste.

Resource

SkillsResource.create

create(body: Doc, opts?: CallOptions)

Enregistrer un skill. Applique un manifeste Skill : crée le skill ou le remplace (un skill remplacé revient à draft, un skill bloqué reste blocked). L'empreinte et la signature sont vérifiées aussitôt : le skill passe à approved si elles sont valides. Un artefact Git ou OCI demande artifact.digest (422 invalid_manifest). apply_status vaut created ou updated. Demande tenant_admin, developer ou application_owner ; l'appelant devient propriétaire ReBAC. Audité sous skill.apply.

Route : /v1/skills (POST).

Nom	Type	Défaut	Requis	Description
body	Doc		oui	Manifeste Skill (kind: Skill, metadata avec nom, version et propriétaire, spec avec description, instructions, permissions, signature et artefact facultatif).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SkillsResource.get

get(name: string, opts?: CallOptions)

Lire un skill. Renvoie le skill avec son manifeste, son contenu, son empreinte, sa signature et sa vérification. Demande la relation ReBAC viewer. 404 skill_not_found.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du skill.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SkillsResource.list

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

Lister les skills. Skills du tenant dans l'ordre des noms, avec version, propriétaire, empreinte, résultat de vérification et statut. Une seule page.

Route : /v1/skills (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SkillsResource.load

load(name: string, opts?: CallOptions)

Charger un skill pour un agent. Skill Loader : renvoie ce dont un runtime a besoin pour utiliser le skill (instructions d'un skill en ligne, artefact, point d'entrée, permissions, dépendances, signataire). Demande la relation ReBAC can_invoke. Refus, chacun audité comme skill.load refusé : - 403 skill_blocked : le skill est blocked ou deprecated ; - 409 skill_digest_mismatch : le contenu ne correspond plus à son empreinte ; - 403 skill_unsigned : la signature n'est pas valide ; - 403 skill_not_granted : avec agent, le skill n'est pas listé dans le manifeste de l'agent ; - 403 skill_permission_denied : le skill demande des scopes que l'agent n'a pas, ou son plafond de classification est inférieur à celui de l'agent.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du skill.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SkillsResource.setStatus

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

Changer le statut d'un skill. approved passe par une promotion : une approbation est ouverte pour tenant_admin ou security_officer et la réponse est 202 avec approval_id et status: pending_approval. Les autres statuts (draft, restricted, deprecated, blocked) s'appliquent aussitôt (200). Demande tenant_admin ou security_officer et la relation ReBAC editor. Audité sous skill.status.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du skill.
body	{ status: string; reason?: string }		oui	Statut visé et raison.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SkillsResource.verify

verify(name: string, opts?: CallOptions)

Vérifier la signature d'un skill. Revérifie l'empreinte du contenu et la signature avec les clés de confiance et enregistre le résultat : verified, method, signer, reason. Un skill vérifié passe à approved, sinon à draft (un skill bloqué reste blocked). Demande tenant_admin, developer, application_owner ou security_officer et la relation ReBAC editor. Audité sous skill.verify.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du skill.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe PluginsResource

Plugins. Registre et cycle de vie d'exécution des plugins : des images OCI signées exécutées par la plateforme dans une sandbox (classe de runtime gVisor, Kata ou Wasm), avec un Deployment et une NetworkPolicy Kubernetes générés à partir du manifeste.

Resource

PluginsResource.create

create(body: Doc, opts?: CallOptions)

Enregistrer un plugin. Applique un manifeste Plugin : crée le plugin ou le met à jour (retour à registered, un plugin bloqué reste blocked), avec la signature vérifiée et enregistrée. Refus : 422 pack_requires_marketplace pour un pack, 422 invalid_manifest quand l'empreinte de oci_ref diffère de artifact.digest, qu'une liste d'autorisation manque pour egress_allowlist ou que les limites dépassent le maximum de la plateforme (4 CPU, 8Gi de mémoire, 3600 s, 1 GPU) ; 409 plugin_installed tant qu'il est installé. Demande tenant_admin, developer ou application_owner ; l'appelant devient propriétaire ReBAC. Audité sous plugin.apply.

Route : /v1/plugins (POST).

Nom	Type	Défaut	Requis	Description
body	Doc		oui	Manifeste Plugin (kind: Plugin, metadata, spec avec description, artefact, signature et sandbox).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

PluginsResource.get

get(name: string, opts?: CallOptions)

Lire un plugin. Renvoie le plugin avec son manifeste, son résultat de vérification et son déploiement généré. Demande la relation ReBAC viewer. 404 plugin_not_found.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du plugin.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

PluginsResource.install

install(name: string, opts?: CallOptions)

Installer un plugin. Installe le plugin dans sa sandbox. Demande tenant_admin et la relation ReBAC owner. Étapes : 1. Un plugin blocked répond 403 plugin_blocked ; un plugin déjà installé est renvoyé tel quel. 2. La signature est revérifiée (403 plugin_unsigned en cas d'échec, audité comme refus). 3. Le Deployment (classe de runtime de la sandbox, système de fichiers racine en lecture seule par défaut) et la NetworkPolicy sont générés, puis appliqués quand Kubernetes est configuré (status: failed avec l'erreur si l'application échoue). Renvoie l'état d'exécution. Audité sous plugin.install.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du plugin.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

PluginsResource.list

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

Lister les plugins. Plugins du tenant dans l'ordre des noms, avec version, empreinte, vérification et statut. Une seule page.

Route : /v1/plugins (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

PluginsResource.status

status(name: string, opts?: CallOptions)

Lire l'état d'exécution d'un plugin. Vue d'exécution : statut, indicateur de vérification, empreinte, date d'installation, classe de runtime, objets rendered (générés) ou applied (appliqués) sur Kubernetes, Deployment et NetworkPolicy et dernière erreur. Demande la relation ReBAC viewer.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du plugin.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

PluginsResource.uninstall

uninstall(name: string, opts?: CallOptions)

Désinstaller un plugin. Supprime le Deployment et la NetworkPolicy de Kubernetes s'il est configuré (502 upstream_error en cas d'échec) et passe le plugin à uninstalled. Seulement pour un plugin installed, installing ou failed (sinon 409 plugin_not_installed). Demande tenant_admin et la relation ReBAC owner. Audité sous plugin.uninstall.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du plugin.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe ConnectorsResource

Connecteurs. Connector Hub : registre des connexions aux systèmes externes (applications SaaS, API, sources de données), leurs identifiants conservés côté serveur, les exécutions de synchronisation, le Credential Broker qui remet des baux de courte durée à la place des secrets, et la Webhook Gateway qui reçoit les événements signés des fournisseurs.

Resource

ConnectorsResource.create

create(body: Doc, opts?: CallOptions)

Enregistrer un connecteur. Applique un manifeste Connector : crée ou met à jour le connecteur (apply_status : created ou updated). Les URL doivent être permises par la politique de sortie réseau ; OAuth2 demande auth.token_url ; les webhooks non signés sont refusés (422 invalid_manifest). Demande tenant_admin, developer ou application_owner. Audité sous connector.apply.

Route : /v1/connectors (POST).

Nom	Type	Défaut	Requis	Description
body	Doc		oui	Manifeste Connector (kind: Connector, metadata, spec avec URL de base, auth, ressources, scopes, synchronisation et webhooks).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.delete

delete(name: string, opts?: CallOptions)

Supprimer un connecteur. Supprime le connecteur et ses identifiants dans le magasin de secrets. Demande tenant_admin. 404 connector_not_found. Audité sous connector.delete.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.get

get(name: string, opts?: CallOptions)

Lire un connecteur. Renvoie le connecteur avec son manifeste, son statut, son propriétaire et ses identifiants configurés (type, noms de champs, date de mise à jour). 404 connector_not_found.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.list

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

Lister les connecteurs. Connecteurs du tenant dans l'ordre des noms, chacun avec les types d'identifiants configurés (jamais leurs valeurs). Une seule page.

Route : /v1/connectors (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.setCredentials

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

Enregistrer les identifiants d'un connecteur. Enregistre des identifiants dans le magasin de secrets et ne renvoie que le type et les noms de champs (201). Demande tenant_admin ou security_officer. Corps : kind plus ses champs : - oauth2_client : client_id, client_secret ; - oauth2_code : code, redirect_uri, code_verifier facultatif ; le code est échangé aussitôt auprès de l'URL de jeton (demande un oauth2_client enregistré, sinon 409 credential_unavailable) et conservé comme oauth2_token ; - api_key : api_key, header facultatif ; - service_account : private_key ou token, client_email et client_id facultatifs ; - basic : username, password ; - webhook_secret : secret. Un type inconnu ou des champs manquants répondent 400 invalid_request. Audité sous connector.credentials.write.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
body	Doc		oui	Type d'identifiant et ses champs. En écriture seule : les valeurs ne sont jamais renvoyées.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.sync

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

Lancer une synchronisation. Met en file une synchronisation (202) et publie connectors.<nom>.sync pour le worker. Le manifeste doit déclarer un mode de synchronisation (409 sync_disabled), le connecteur doit être actif (409 connector_disabled), les ressources doivent être lisibles (400 invalid_request) et aucune autre exécution ne doit être en file ou en cours (409 sync_in_progress). Une synchronisation incrémentale part du curseur de la dernière exécution réussie sauf avec full. La politique connector.sync est évaluée. Demande tenant_admin, developer ou agent. Audité sous connector.sync.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
body	Doc	{}	non	Ressources et indicateur de synchronisation complète facultatifs.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.syncRuns

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

Lister les synchronisations d'un connecteur. Exécutions de synchronisation du connecteur, de la plus récente à la plus ancienne : mode, statut, ressources, curseur et dates.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.test

test(name: string, opts?: CallOptions)

Tester un connecteur. Construit les en-têtes d'authentification à partir des identifiants enregistrés et, quand le manifeste a une URL de base, lui envoie un GET. Renvoie ok, credentials, http_status, latency_ms et un code error en cas d'échec (egress_denied, upstream_unavailable, erreurs d'identifiants) ; un test en échec est un 200 avec ok: false. La politique connector.test est évaluée. Demande tenant_admin, developer ou application_owner. Audité sous connector.test.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsResource.update

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

Modifier un connecteur. Modifie le statut ou le propriétaire. Désactiver un connecteur révoque immédiatement ses baux d'identifiants. Demande tenant_admin, developer ou application_owner. Audité sous connector.update.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du connecteur.
body	Doc		oui	Champs à modifier ; ceux omis sont conservés.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe CredentialsResource

Connecteurs. Connector Hub : registre des connexions aux systèmes externes (applications SaaS, API, sources de données), leurs identifiants conservés côté serveur, les exécutions de synchronisation, le Credential Broker qui remet des baux de courte durée à la place des secrets, et la Webhook Gateway qui reçoit les événements signés des fournisseurs.

Resource

CredentialsResource.lease

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

Obtenir un bail d'identifiants. Émet un bail de courte durée sur un connecteur à la place de son secret (201) : lease_id, token (montré une seule fois), scopes, expires_at, ttl_seconds. Les scopes demandés doivent être déclarés par le connecteur (403 scope_not_allowed ; par défaut : tous) ; le connecteur doit être actif (409 connector_disabled). Avec on_behalf_of, l'utilisateur doit détenir la relation can_invoke sur le connecteur (403 relation_required). Demande tenant_admin, developer ou agent. Audité sous credential.lease.

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

Nom	Type	Défaut	Requis	Description
body	{ connector: string; scopes?: string[]; ttl_seconds?: number } & Doc		oui	Connecteur, scopes, durée de vie, run et utilisateur représenté.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Interface WebhookHeaders

En-têtes d'un webhook signé : X-EAI-Tenant, X-EAI-Signature et X-EAI-Delivery facultatif.

Champs :

Nom	Type	Requis	Description
X-EAI-Tenant	string	oui	Tenant pour lequel le webhook est envoyé.
X-EAI-Signature	string	oui	Signature t=<unix>,v1=<hex HMAC-SHA256> de <t>.<raw body>.
X-EAI-Delivery	string	non	Identifiant de livraison, utilisé pour écarter les doublons.

Classe WebhooksResource

Connecteurs. Connector Hub : registre des connexions aux systèmes externes (applications SaaS, API, sources de données), leurs identifiants conservés côté serveur, les exécutions de synchronisation, le Credential Broker qui remet des baux de courte durée à la place des secrets, et la Webhook Gateway qui reçoit les événements signés des fournisseurs.

Resource

Attributs :

Nom	Type	Requis	Description
connector	string,	oui	Connecteur qui reçoit la charge utile de deliver (POST /v1/webhooks/{connector}).
opts	CallOptions,	non	Options par appel de deliver ; les en-têtes de signature y sont ajoutés.
payload	unknown,	oui	Charge utile de deliver, sérialisée en JSON puis signée octet par octet.
signing	{ secret: string; tenant: string; deliveryId?: string },	oui	Réglages de signature de deliver : secret, tenant et identifiant de livraison facultatif.

WebhooksResource.deliver

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

Recevoir un webhook de fournisseur. Point d'entrée du fournisseur, sans authentification de la plateforme. En-têtes : X-EAI-Tenant (slug du tenant, sinon 400 tenant_required), X-EAI-Signature (t=<secondes unix>,v1=<HMAC-SHA256 hexadécimal de "<t>." + corps brut> ; X-EAI-Timestamp peut porter l'horodatage), X-EAI-Delivery facultatif (identifiant de dédoublonnage). Étapes : 1. Le connecteur doit exister, être actif et avoir les webhooks activés (404 connector_not_found). 2. Signature vérifiée avec le webhook_secret enregistré ou la référence de secret du manifeste (401 invalid_signature) ; horodatage à moins de 5 minutes (401 webhook_replay) ; une livraison déjà acceptée répond 409 webhook_duplicate. 3. Le corps JSON est contrôlé comme contenu non fiable (injection de prompt bloquée), puis publié sous connectors.<nom>.webhook, ce qui peut lancer des runs déclenchés. Répond 202 avec delivery_id, event_id et triggered. Chaque livraison est enregistrée et auditée sous webhook.receive.

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

Nom	Type	Défaut	Requis	Description
connector	string		oui	Nom du connecteur auquel le fournisseur envoie.
payload	unknown		oui	Charge utile brute du fournisseur ; la signature est vérifiée sur ces octets exacts, quel que soit le type de contenu.
signing	{ secret: string; tenant: string; deliveryId?: string }		oui	Secret de signature, tenant et identifiant de livraison facultatif ; un identifiant est généré en son absence.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

WebhooksResource.deliveries

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

Lister les livraisons de webhooks. Livraisons de webhooks reçues, de la plus récente à la plus ancienne : connecteur, identifiant de livraison, validité de la signature, statut (accepted, rejected, duplicate), raison, SHA-256 de la charge utile et événement publié. La charge utile elle-même n'est pas conservée ici.

Route : /v1/webhooks/deliveries (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Classe ChannelsResource

Canaux. Channel Gateway : les points d'entrée où les utilisateurs finaux parlent aux agents (web, mobile, e-mail, Slack, Teams, WhatsApp, SMS, voix, API, et les canaux Navin Discord, Telegram, Matrix, Mattermost et Signal). Un message entrant devient un message de session et lance un run de l'agent du canal, dans des limites de taille, de débit et de sessions et avec DLP.

Resource

ChannelsResource.create

create(body: Doc, opts?: CallOptions)

Créer ou mettre à jour un canal. Applique un manifeste Channel (apply_status : created ou updated) ; project (identifiant ou slug, par défaut l'en-tête X-Project) le rattache à un projet, et un canal d'un autre projet n'est jamais repris (409 channel_project_conflict). L'agent de agent_ref doit exister (404 agent_not_found) ; signed_webhook demande auth.secret_ref (422 invalid_manifest). Demande tenant_admin, developer ou application_owner. Audité sous channel.apply.

Route : /v1/channels (POST).

Nom	Type	Défaut	Requis	Description
body	Doc		oui	Manifeste Channel (kind: Channel, metadata, spec avec type, agent, auth, limites, DLP et sessions).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ChannelsResource.delete

delete(name: string, opts?: CallOptions)

Supprimer un canal. Supprime le canal. Demande tenant_admin. 404 channel_not_found. Audité sous channel.delete.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du canal.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ChannelsResource.get

get(name: string, opts?: CallOptions)

Lire un canal. Renvoie le canal avec son manifeste, son type, son agent, son statut, son projet et son preset. 404 channel_not_found.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du canal.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ChannelsResource.inbound

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

Envoyer un message entrant. Remet un message d'un utilisateur final (202) et renvoie session_id, session_created, message_id, run_id (ou run_skipped quand l'agent n'est pas actif) et le résultat DLP. Demande tenant_admin, developer ou agent. Étapes : 1. Le canal doit être actif (409 channel_disabled) ; un canal signed_webhook vérifie X-EAI-Signature (t=<secondes unix>,v1=<HMAC-SHA256 hexadécimal de "<t>." + corps brut>, fenêtre de 5 minutes ; 401 invalid_signature). 2. La politique channel.inbound est évaluée ; la taille (413 message_too_large) et le débit par utilisateur (429 rate_limited) sont contrôlés. 3. La DLP entrante s'exécute (detect par défaut ; block répond 403 dlp_blocked, mask enregistre le texte masqué). 4. La session ouverte de l'utilisateur et de la conversation est réutilisée, ou une nouvelle est ouverte (429 too_many_sessions, 409 session_closed au-delà de max_session_minutes). 5. Le message est ajouté et un run de l'agent du canal démarre avec le déclencheur channel.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du canal.
body	Doc		oui	Message JSON : text (1 à 1000000 caractères, obligatoire), user (identifiant externe de l'utilisateur, 300 caractères au plus ; par défaut l'appelant), conversation_id (300 caractères au plus ; par défaut l'utilisateur) et metadata (conservées avec le message). Les octets bruts servent au contrôle de signature.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ChannelsResource.list

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

Lister les canaux. Canaux du tenant dans l'ordre des noms ; project (identifiant ou slug) ne garde que les canaux de ce projet (404 project_not_found). Une seule page.

Route : /v1/channels (GET).

Nom	Type	Défaut	Requis	Description
params	ListParams & { project?: string }		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ChannelsResource.sessions

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

Lister les sessions d'un canal. Sessions ouvertes sur le canal, de la plus récemment mise à jour à la plus ancienne, 500 au plus.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du canal.
params	ListParams		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

ChannelsResource.update

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

Modifier un canal. Modifie le statut (active ou disabled ; un canal désactivé refuse les messages entrants) ou le propriétaire. Demande tenant_admin, developer ou application_owner. Audité sous channel.update.

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

Nom	Type	Défaut	Requis	Description
name	string		oui	Nom du canal.
body	Doc		oui	Champs à modifier ; ceux omis sont conservés.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Alias de type NavinLibraryKind

Type d'élément de la bibliothèque Navin : skills, plugins, commands, agents, mcp-presets ou channels.

Définition : "skills" \| "plugins" \| "commands" \| "agents" \| "mcp-presets" \| "channels".

Classe NavinLibraryResource

Bibliothèque Navin. La bibliothèque Navin est le catalogue embarqué de skills, plugins, commandes, agents, presets MCP et canaux prêts à l'emploi. Un projet active ce dont il a besoin, installe des serveurs MCP et des canaux à partir de presets et garde ses propres règles, les instructions durables que reçoit chaque run du projet.

Resource

NavinLibraryResource.activate

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

Activer un élément de la bibliothèque. Active un skill, un plugin (avec ses skills, commandes et agents), une commande ou un agent pour le projet (201). Un skill est enregistré dans le Skill Registry, vérifié par son empreinte de bibliothèque ; un nom de skill déjà pris par un skill hors bibliothèque répond 409 navin_skill_name_taken. Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. 422 navin_library_kind_not_activable ; 404 navin_library_item_not_found. Audité sous navin_library.activate.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
body	{ kind: "skill" | "plugin" | "command" | "agent"; name: string }		oui	Type et nom de l'élément à activer.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.deactivate

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

Désactiver un élément de la bibliothèque. Retire une activation du projet ; un plugin emporte les skills, commandes et agents qu'il avait apportés. Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. 404 navin_library_activation_not_found. Audité sous navin_library.deactivate.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
activationId	string		oui	Identifiant (UUID) de l'activation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.deleteRule

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

Supprimer une règle de projet. Supprime la règle ; les runs du projet ne la reçoivent plus. Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. 404 rule_not_found. Audité sous project.rule.delete.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
name	string		oui	Nom de la règle.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.importRules

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

Importer les fichiers de règles d'un dépôt. Importe les fichiers de règles d'un dépôt (.navin/rules, .cursor/rules/*.mdc avec leur frontmatter, .cursorrules, .clinerules, .windsurfrules, .github/copilot-instructions.md) ; chaque fichier reconnu crée ou remplace une règle. Les autres fichiers sont signalés dans skipped avec une raison (not_a_rule_file, empty, too_large). 200 fichiers au plus (400 invalid_request). Demande tenant_admin, developer ou application_owner et la relation ReBAC editor.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
files	{ path: string; content: string }[]		oui	Fichiers à importer (1 à 200).
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

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)

Installer un canal depuis la bibliothèque. Crée un canal du projet à partir d'un adaptateur de canal Navin (201). Le contrat de configuration de l'adaptateur est vérifié : des champs inconnus, secrets ou en lecture seule dans settings et des champs non secrets dans secret_refs répondent 422 channel_field_invalid, un type de valeur incorrect aussi, des exigences manquantes 422 channel_field_missing ; les secrets ne sont que des références openbao:// ou env:// (422 channel_secret_ref_required). Par défaut : auth api_key, limites de 65536 octets par message et 60 par minute, DLP detect en entrée et mask en sortie. Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. Audité sous navin_library.channel_install.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
name	string		oui	Nom de l'adaptateur de canal Navin.
body	{ name?: string; agent_ref?: string; settings?: Doc; secret_refs?: Record<string, string>; auth?: Doc; limits?: Record<string, number>; dlp?: Record<string, string> }		oui	Nom du canal, agent, réglages, références de secrets, authentification, limites et DLP.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

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)

Installer un serveur MCP depuis un preset. Enregistre un serveur MCP du projet dans la passerelle MCP à partir d'un preset Navin (201), en HTTP streamable ou SSE. Un preset stdio s'exécute là où tourne sa commande (la page MCP du Navin Manager) : donnez son point d'accès HTTP dans url ; ses champs d'environnement et d'arguments sont renvoyés dans bridge_fields. Erreurs : 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 (un champ secret doit être une référence openbao:// ou env://), 422 mcp_preset_unsupported. Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. Audité sous navin_library.mcp_install.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
name	string		oui	Nom du preset MCP.
body	{ name?: string; url?: string; transport?: "streamable_http" | "sse"; values?: Record<string, string | number | boolean>; credential_refs?: Record<string, string>; allowed_tools?: string[] }		oui	Nom du serveur, point d'accès, transport, champs du preset, références de secrets et outils permis.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.item

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

Lire un élément de la bibliothèque. Un élément avec son contenu (SKILL.md et fichiers d'un skill, plugin.json et README d'un plugin, Markdown d'une commande ou d'un agent, preset MCP ou contrat de canal complet). 404 navin_library_item_not_found.

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

Nom	Type	Défaut	Requis	Description
kind	NavinLibraryKind		oui	Type d'élément : skills, plugins, commands, agents, mcp-presets ou channels.
name	string		oui	Nom de l'élément.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.items

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

Lister les éléments d'un type. Éléments d'un type : skills, plugins, commands, agents, mcp-presets ou channels (q cherche dans le nom et la description, category filtre les skills, plugins et presets MCP). Un type inconnu répond 404 navin_library_kind_unknown.

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

Nom	Type	Défaut	Requis	Description
kind	NavinLibraryKind		oui	Type d'élément : skills, plugins, commands, agents, mcp-presets ou channels.
query	{ q?: string; category?: string }		non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.project

project(projectId: string, opts?: CallOptions)

Voir ce qu'un projet utilise de la bibliothèque. Version de la bibliothèque, activations du projet avec le nombre par type, et serveurs MCP et canaux du projet (avec le preset dont ils viennent). Demande la relation ReBAC viewer sur le projet.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

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)

Créer ou remplacer une règle de projet. Crée (201) ou remplace (200) une règle du projet. Le nom compte 1 à 64 lettres, chiffres, ., _ ou - (un suffixe .md est retiré, readme est refusé ; 422 rule_name_invalid). Un contenu vide répond 422 rule_empty, plus de 64 Kio 413 rule_too_large ; une règle conditionnelle demande des globs ou une description (422 rule_scope_required). Demande tenant_admin, developer ou application_owner et la relation ReBAC editor. Audité sous project.rule.put.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
name	string		oui	Nom de la règle.
body	{ content: string; mode?: "always" | "conditional"; description?: string; globs?: string[]; source?: "navin" | "cursor" | "cursor_legacy" | "cline" | "windsurf" | "copilot" }		oui	Contenu, mode, description, globs et source de la règle.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.rules

rules(projectId: string, opts?: CallOptions)

Lister les règles du projet. Règles du projet par mode puis par nom, chacune avec source, chemin source, description, globs, contenu, empreinte et taille en octets. Demande la relation ReBAC viewer.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.rulesPrompt

rulesPrompt(projectId: string, opts?: CallOptions)

Lire la section de prompt des règles. La section de prompt que reçoit chaque run du projet : règles always insérées (chacune coupée à 8000 caractères), règles conditionnelles listées avec leur description et leurs globs. Renvoie prompt, les nombres always et conditional et l'empreinte digest du texte (vide si le projet n'a aucune règle). Demande la relation ReBAC viewer.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

NavinLibraryResource.summary

summary(opts?: CallOptions)

Lire le résumé de la bibliothèque. Version du paquet navin embarqué, nombre d'éléments par type et fichiers de règles lus dans un dépôt. 503 navin_library_unavailable quand le catalogue n'est pas livré.

Route : /v1/navin-library (GET).

Nom	Type	Défaut	Requis	Description
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Alias de type McpInstanceStatus

État d'une instance MCP Runtime : provisioning, ready, failed, terminating ou terminated.

Définition : "provisioning" \| "ready" \| "failed" \| "terminating" \| "terminated".

Classe McpRuntimeResource

Runtime MCP. MCP Runtime : des instances isolées de serveur MCP démarrées à la demande pour un utilisateur d'un projet, à partir des modèles du catalogue de la plateforme, exécutées par ToolHive dans l'espace de noms du projet et joignables via la MCP Gateway.

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)

Démarrer une instance MCP. Démarre une instance MCP isolée de l'appelant dans le projet (202) : MCPServer ToolHive propre, identifiants propres, prête quand ToolHive la signale Ready (lisez l'instance pour la suivre). Demande tenant_admin, developer ou application_owner et la relation ReBAC editor sur le projet. Contrôles : le MCP Runtime est activé (409 mcp_runtime_disabled) ; le modèle, ses hôtes et ses rôles de base de données sont permis par la politique du projet (403 mcp_template_not_allowed, mcp_host_not_allowed, mcp_database_role_not_allowed) ; un modèle à identifiants personnels demande credential_ref (422 mcp_credential_required) ; agents, outils et nom sont valides (422) ; quotas par utilisateur et par projet (409 mcp_instance_quota) ; aucune autre instance de l'appelant du même nom (409 mcp_instance_exists). Un provisionnement en échec détruit l'instance et renvoie l'erreur. Audité sous mcp.instance.create.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
body	{ template: string; name?: string; params?: Record<string, string | number | string[]>; credential_ref?: string; agents?: string[]; allowed_tools?: string[]; idle_timeout_seconds?: number }		oui	Modèle, nom, paramètres, identifiant personnel, agents, outils permis et temps d'inactivité.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpRuntimeResource.destroyInstance

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

Détruire une instance MCP. Détruit l'instance à la fin de la tâche : identifiants révoqués, ressources supprimées, entrée de passerelle désactivée, journal conservé. Permis pour son propriétaire, ou tenant_admin et security_officer (enregistré comme destruction par un administrateur). Demande la relation ReBAC viewer sur le projet. Renvoie l'instance et son journal. 404 mcp_instance_not_found.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
instanceId	string		oui	Identifiant (UUID) de l'instance.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpRuntimeResource.instance

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

Lire une instance MCP. L'instance (son état relu auprès de ToolHive tant qu'elle est en provisionnement ou prête) et son journal de cycle de vie dans events. credential_active indique si des identifiants sont actuellement émis. Visible par son propriétaire, tenant_admin et security_officer ; demande la relation ReBAC viewer sur le projet. 404 mcp_instance_not_found.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
instanceId	string		oui	Identifiant (UUID) de l'instance.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpRuntimeResource.instances

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

Lister les instances MCP d'un projet. Renvoie enabled (si le MCP Runtime tourne sur cette plateforme), la policy du projet (valeurs par défaut si elle n'est pas configurée), l'état du catalogue, les templates et les instances, de la plus récente à la plus ancienne, 500 au plus : les siennes pour un utilisateur, toutes pour tenant_admin et security_officer. Demande la relation ReBAC viewer sur le projet.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
query	{ status?: McpInstanceStatus }		non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpRuntimeResource.jwks

jwks(opts?: CallOptions)

Lire les clés de vérification du runtime MCP. Clés publiques de vérification des jetons que la MCP Gateway remet aux proxys ToolHive (aucun secret : des clés publiques seulement, comme tout JWKS OIDC). Lues sans authentification par le MCPOIDCConfig eai-mcp-runtime de chaque espace de noms de projet. 503 context_authority_unavailable quand le registre de clés est illisible.

Route : /v1/mcp/runtime/jwks (GET).

Nom	Type	Défaut	Requis	Description
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

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)

Définir la politique du runtime MCP d'un projet. Remplace la politique du MCP Runtime du projet : modèles, hôtes, rôles de base de données, temps d'inactivité, durée de vie et quotas. Des modèles inconnus, des motifs d'hôte ou des noms de rôle invalides répondent 422 mcp_policy_invalid. Les instances nouvelles et réveillées la suivent. Demande tenant_admin et la relation ReBAC editor sur le projet. Audité sous mcp.runtime.policy.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
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 }		oui	La politique complète ; les champs omis prennent leur valeur par défaut.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpRuntimeResource.startInstance

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

Redémarrer une instance endormie ou en échec. Redémarre maintenant une instance endormie ou en échec (compteur de pannes remis à zéro) : modèle et politique du projet revérifiés, nouvelle génération et nouveaux identifiants ; prête quand ToolHive la signale Ready (lisez l'instance pour la suivre). 409 mcp_instance_busy pendant une autre opération de cycle de vie. Permis pour son propriétaire, tenant_admin et security_officer ; demande la relation ReBAC viewer sur le projet. Renvoie l'instance et son journal (202).

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
instanceId	string		oui	Identifiant (UUID) de l'instance.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

McpRuntimeResource.stopInstance

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

Endormir une instance MCP. Arrête l'instance maintenant (identifiants révoqués, ressources supprimées) : elle s'endort, son entrée de passerelle reste et son prochain appel la recrée. Permis pour son propriétaire, tenant_admin et security_officer ; demande la relation ReBAC viewer sur le projet. Renvoie l'instance et son journal.

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

Nom	Type	Défaut	Requis	Description
projectId	string		oui	Identifiant (UUID) ou slug du projet.
instanceId	string		oui	Identifiant (UUID) de l'instance.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Alias de type FileScanStatus

État d'un fichier analysé : quarantined, released ou blocked.

Définition : "quarantined" \| "released" \| "blocked".

Alias de type FileScanVerdict

Verdict d'une analyse : clean, malware, suspicious, unscannable, scan_error ou policy_violation.

Définition : "clean" \| "malware" \| "suspicious" \| "unscannable" \| "scan_error" \| "policy_violation".

Alias de type FileScanSource

Source d'un fichier analysé : knowledge, media, multimodal, transcription, connector, channel ou api.

Définition : "knowledge" \| "media" \| "multimodal" \| "transcription" \| "connector" \| "channel" \| "api".

Interface FileScanRecord

Enregistrement d'une analyse de fichier (ClamAV et YARA-X, puis les contrôles intégrés).

Champs :

Nom	Type	Requis	Description
id	string	oui	Identifiant de l'enregistrement d'analyse.
status	FileScanStatus	oui	État du fichier : quarantined, released ou blocked.
verdict	FileScanVerdict | null	oui	Verdict de l'analyse, null tant qu'elle est en cours.
reasons	string[]	oui	Motifs du verdict.
source	FileScanSource	oui	Provenance du fichier, par exemple knowledge, media ou api.
source_ref	string | null	non	Référence du fichier dans sa source.
filename	string | null	non	Nom du fichier analysé, s'il a été fourni.
mime_type	string | null	non	Type de média du contenu, par exemple application/pdf ou image/png.
detected_type	string | null	non	Type de fichier détecté à partir du contenu.
size_bytes	number	oui	Taille du fichier en octets.
sha256	string	oui	Empreinte SHA-256 du fichier.
engines	Doc	oui	Résultats de chaque moteur d'analyse.
sample_retained	boolean	oui	Indique si un échantillon du fichier est conservé.
rescan_of	string | null	non	Identifiant de l'analyse que celle-ci répète, pour une nouvelle analyse.
created_by	string | null	non	Principal qui a envoyé le fichier.
created_at	string	oui	Date de création de l'enregistrement.
scanned_at	string | null	non	Date de fin de l'analyse.
expires_at	string | null	non	Date et heure (ISO 8601, UTC) après lesquelles l'élément n'est plus valide.

Interface FileSecurityPolicyUpdate

Champs modifiables de la politique du tenant (les règles locked ne peuvent jamais être changées).

Champs :

Nom	Type	Requis	Description
max_file_bytes	number	non	Plus grand fichier accepté, en octets : de 1024 au plafond de la plateforme EAI_FILE_SCAN_MAX_BYTES (valeur par défaut). Un fichier plus grand est bloqué pour violation de politique sans atteindre les moteurs.
allowed_types	string[]	non	Types de fichiers détectés acceptés, parmi les types connus (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). Par défaut : tous les types connus sauf executable.
allow_archives	boolean	non	Indique si les archives (zip, gzip, tar, 7z, rar) sont acceptées ; vrai par défaut.
block_office_macros	boolean	non	Indique si les documents Office avec macros sont bloqués ; vrai par défaut. Si faux, la macro est seulement signalée dans les raisons.
block_type_mismatch	boolean	non	Indique si un fichier dont le type détecté contredit son type de média déclaré est bloqué ; vrai par défaut.
retain_samples	boolean	non	Indique si un échantillon chiffré de chaque fichier bloqué est conservé pour une nouvelle analyse ultérieure ; vrai par défaut.
quarantine_retention_days	number	non	Nombre de jours de conservation d'un échantillon avant sa suppression par la tâche de rétention, de 1 à 365, 30 par défaut.
max_signature_age_hours	number	non	Âge maximal des signatures ClamAV en heures, de 1 à 720, 48 par défaut. Des signatures plus anciennes ou sans date sont périmées.
stale_signatures	"warn" | "block"	non	Effet de signatures ClamAV périmées sur une analyse : warn (par défaut) ajoute seulement une raison, block bloque le fichier avec le verdict scan_error.

Interface FileScanInput

Entrée de FileSecurityResource.scan : contenu base64 ou octets, nom de fichier et type MIME.

Champs :

Nom	Type	Requis	Description
contentBase64	string	non	Contenu du fichier, encodé en base64.
data	Uint8Array | ArrayBuffer	non	Octets du fichier, encodés en base64 par le SDK (ou fournir contentBase64).
filename	string	non	Nom du fichier à analyser, envoyé comme filename.
mimeType	string	non	Type de média du contenu, par exemple application/pdf ou image/png.

Classe FileSecurityResource

Sécurité des fichiers. Contrôles antivirus et de contenu de chaque fichier qui entre dans la plateforme, avant qu'un analyseur, un modèle ou un magasin ne le voie.

Resource

FileSecurityResource.getScan

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

Lire un enregistrement d'analyse. Un enregistrement d'analyse : statut, verdict, raisons, source et sa référence, nom de fichier, type déclaré et détecté, taille, SHA-256, réponse de chaque moteur, échantillon conservé ou non, analyse qu'il reprend, créateur et dates (création, analyse, expiration de l'échantillon). Demande un principal de tenant ; l'enregistrement d'un autre n'est visible que par tenant_admin, security_officer et auditor (404 not_found sinon).

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

Nom	Type	Défaut	Requis	Description
scanId	string		oui	Identifiant de l'enregistrement d'analyse.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Retour : Promise<FileScanRecord>. Réponse JSON décodée de l'opération « Lire un enregistrement d'analyse ».

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.listScans

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

Lister les enregistrements d'analyse. Enregistrements d'analyse du tenant, du plus récent au plus ancien ; un principal sans rôle de lecteur (tenant_admin, security_officer, auditor) ne voit que ses propres analyses. Demande un principal de tenant. Un statut, un verdict ou une source inconnus répondent 400 invalid_request ; un curseur mal formé 400 invalid_cursor.

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

Nom	Type	Défaut	Requis	Description
params	ListParams & { status?: FileScanStatus; verdict?: FileScanVerdict; source?: FileScanSource }		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.policy

policy(opts?: CallOptions)

Lire la politique de sécurité des fichiers. Politique effective du tenant : les règles verrouillées, chaque règle modifiable (valeurs enregistrées par-dessus les valeurs par défaut, la taille jamais au-dessus du plafond de la plateforme EAI_FILE_SCAN_MAX_BYTES), les types de fichiers connus, et la date et l'auteur de la dernière modification. Demande un principal de tenant avec tenant_admin, security_officer ou auditor (403 forbidden).

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

Nom	Type	Défaut	Requis	Description
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.purgeSample

purgeSample(scanId: string, opts?: CallOptions)

Purger l'échantillon d'un fichier bloqué. Supprime tout de suite l'échantillon chiffré d'un fichier bloqué, sans attendre la fin de sa rétention, et répond sample_retained: false. La purge est auditée (file_security.sample.purge) avec le SHA-256 du fichier. Demande un principal de tenant avec security_officer ou tenant_admin (403 forbidden). Une analyse inconnue ou non visible par l'appelant répond 404 not_found.

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

Nom	Type	Défaut	Requis	Description
scanId	string		oui	Identifiant de l'enregistrement d'analyse.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.rescan

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

Analyser à nouveau l'échantillon d'un fichier bloqué. Analyse à nouveau l'échantillon conservé d'un fichier bloqué, par exemple après une mise à jour des signatures, et répond 201 avec un nouvel enregistrement dont rescan_of désigne l'analyse d'origine. L'envoi d'origine n'est jamais libéré : un résultat sain ne fait qu'informer. Demande un principal de tenant avec security_officer ou tenant_admin (403 forbidden). Sans échantillon conservé : 409 file_sample_unavailable ; analyse inconnue ou invisible : 404 not_found.

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

Nom	Type	Défaut	Requis	Description
scanId	string		oui	Identifiant de l'enregistrement d'analyse bloqué dont l'échantillon est analysé à nouveau.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Retour : Promise<FileScanRecord>. Réponse JSON décodée de l'opération « Analyser à nouveau l'échantillon d'un fichier bloqué ».

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.scan

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

Analyser un fichier sans l'ingérer. Analyse un fichier sans l'ingérer et répond 201 avec l'enregistrement, released ou blocked (un fichier bloqué n'est pas une erreur ici). Tout principal de tenant peut l'appeler (403 tenant_required sinon).

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

Nom	Type	Défaut	Requis	Description
input	FileScanInput		oui	Fichier à analyser : contentBase64 ou data, plus filename et mimeType facultatifs ; sans contenu, une TypeError est levée.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Retour : Promise<FileScanRecord>. Réponse JSON décodée de l'opération « Analyser un fichier sans l'ingérer ».

Erreurs levées : TypeError, les erreurs typées du transport (Erreurs).

FileSecurityResource.stats

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

Lire les statistiques d'analyse. Nombre d'analyses sur les window_hours dernières heures, par statut, par verdict et par source, avec l'heure du dernier fichier bloqué. Les lecteurs (tenant_admin, security_officer, auditor) comptent toutes les analyses du tenant, les autres seulement les leurs. Demande un principal de tenant. Une fenêtre hors de 1 à 8784 heures répond 400 invalid_request.

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

Nom	Type	Défaut	Requis	Description
params	{ window_hours?: number }		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.status

status(opts?: CallOptions)

Lire l'état des moteurs d'analyse. Mode (enforce ou dev), disponibilité, chaîne de traitement et chaque passerelle ClamAV et worker YARA-X, sondés en direct : version, version des signatures, publication et âge avec un indicateur stale au regard de la politique, version, empreinte, nombre et heure de chargement des règles, latence. L'instance est prête quand chaque moteur a au moins un point d'accès sain (en mode enforce, ou quand il est configuré). Demande tenant_admin, security_officer ou auditor (403 forbidden).

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

Nom	Type	Défaut	Requis	Description
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

FileSecurityResource.updatePolicy

updatePolicy(body: FileSecurityPolicyUpdate, opts?: CallOptions)

Modifier la politique de sécurité des fichiers. Modifie les règles modifiables fournies dans le corps ; les autres règles gardent leur valeur. Les tailles ne peuvent être que plus strictes que le plafond de la plateforme, et les règles verrouillées ne changent jamais (422 file_security_rule_locked). Un champ inconnu, un type inconnu ou une valeur hors bornes répond 422 invalid_request avec le champ et la raison. Demande un principal de tenant avec security_officer ou tenant_admin (403 forbidden). La modification est auditée (file_security.policy.update) avec les valeurs avant et après ; la réponse est la nouvelle politique effective.

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

Nom	Type	Défaut	Requis	Description
body	FileSecurityPolicyUpdate		oui	Règles modifiables à changer ; les champs omis gardent leur valeur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

Fonctions

signWebhook

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

Signe le corps brut d'un webhook pour les clients qui envoient des événements à la plateforme : X-EAI-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, plus X-EAI-Tenant et l'identifiant de dédoublonnage facultatif X-EAI-Delivery. Utilise WebCrypto (Node 18+, navigateurs).

Nom	Type	Défaut	Requis	Description
secret	string		oui	Secret HMAC partagé du webhook.
rawBody	string		oui	Corps brut à signer, exactement tel qu'envoyé.
options	{ tenant: string; deliveryId?: string; timestamp?: number }		oui	Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation).

Retour : Promise<WebhookHeaders>. Les en-têtes à envoyer ; lève une erreur quand WebCrypto est absent.

Erreurs levées : Error.

verifyWebhook

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

Vérifie X-EAI-Signature: t=<unix>,v1=<hex> sur "<t>.<raw body>" avec une comparaison en temps constant et une tolérance d'horodatage (300 s par défaut). Renvoie false en cas de non-correspondance ou d'en-tête mal formé.

Nom	Type	Défaut	Requis	Description
secret	string		oui	Secret HMAC partagé du webhook.
rawBody	string		oui	Corps brut reçu, avant toute analyse.
header	string | null | undefined		oui	Valeur de l'en-tête X-EAI-Signature reçu.
options	{ toleranceSeconds?: number; now?: number }	{}	non	Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation).

Retour : Promise<boolean>. Vrai quand une signature v1 correspond et que l'horodatage est dans la tolérance.