Référence API de NextPDF Connect

En bref

Cette page est la référence des symboles du serveur NextPDF Connect (nextpdf/server). Elle liste chaque outil par son nom d’outil enregistré et sa classe d’implémentation, puis documente le service gRPC NextPDFConnect avec ses méthodes Remote Procedure Call (RPC) et ses messages de requête et de réponse. Elle énonce le contrat d’authentification, d’erreur et de limitation de débit partagé par chaque transport.

Le serveur expose un registre unique d’outils au travers de trois transports — le Model Context Protocol (MCP) sur l’entrée et la sortie standard, une interface de programmation applicative (API) Representational State Transfer (REST) et gRPC. Les détails filaires de chaque transport sont décrits sur leur propre page : voir Transport MCP, Transport REST et Transport gRPC. Cette page catalogue les symboles exposés par ces transports.

Les noms d’outils, les classes et les niveaux de risque ci-dessous proviennent des implémentations d’outils dans src/Tools/. Le nombre d’outils qu’un déploiement expose effectivement est déterminé à l’exécution ; voir Catalogue d’outils. La résolution des niveaux est expliquée dans Démarrage et découverte.

Disponibilité des transports

Un outil est accessible via le transport exécuté par un déploiement. Les transports sont des processus indépendants ; en lancer un ne démarre pas les autres.

Transport	Point d’entrée	Format filaire	Authentification
MCP	bin/nextpdf-mcp	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 sur stdio	Isolation par processus du système d’exploitation (pas de clé d’API)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Clé d’API porteuse dans l’en-tête Authorization de la requête
gRPC	bin/nextpdf-grpc	Protocol Buffers, paquet nextpdf.connect.v1	Jeton porteur dans le champ authorization des métadonnées d’appel

En MCP, un outil est appelé par tools/call avec son nom d’outil enregistré. En REST et gRPC, les mêmes capacités du moteur sont exposées via les surfaces de rendu, d’opération et de capacité ; voir le tableau des routes Transport REST et le tableau RPC Transport gRPC.

Authentification et niveau de risque

Authentification par clé d’API

Les transports REST et gRPC exigent une clé d’API porteuse pour chaque requête, sauf pour les sondes de santé non authentifiées. Une clé a la forme npk_live_{kid}_{secret} : le kid est un identifiant de huit caractères qui sert à retrouver l’enregistrement, et le secret fournit l’entropie. Le serveur ne stocke qu’un condensé SHA-256 de la clé et compare le jeton présenté en temps constant, de sorte qu’une mauvaise clé ne révèle aucune information par timing. REST lit le jeton depuis l’en-tête Authorization: Bearer … ; gRPC lit le même jeton depuis les métadonnées d’appel authorization. Le transport stdio MCP n’a pas de clé d’API parce qu’il s’agit d’un sous-processus local approuvé par le client qui le lance. Le modèle d’authentification est détaillé dans Sécurité et exploitation.

Les quatre niveaux de risque

Chaque outil déclare l’un des quatre niveaux de risque ordonnés, définis par l’énumération RiskLevel dans src/Config/RiskLevel.php.

Niveau	Cas d’énumération	Valeur	Effet
Safe	RiskLevel::Safe	0	Lecture seule, aucun effet de bord. S’exécute automatiquement.
Caution	RiskLevel::Caution	1	Crée ou modifie de l’état en mémoire. S’exécute automatiquement, journalisé à des fins d’audit.
Review	RiskLevel::Review	2	Produit une sortie qui pourrait être détournée. S’exécute automatiquement, journalisé à des fins d’audit.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Destructif, juridique ou critique pour la confidentialité. Exige une confirmation humaine.

Le risque effectif d’un outil est déterminé à deux seuls endroits : la déclaration riskLevel() de l’outil lui-même, et une surcharge de configuration optionnelle définie par l’opérateur, qui ne peut qu’augmenter le risque, jamais l’abaisser pour un outil ApprovalRequired. Voir Niveaux de risque HITL et Configuration.

Comment circulent les jetons d’approbation

Lorsqu’un outil ApprovalRequired est invoqué sans jeton valide, la ConfirmationGate (src/Mcp/ConfirmationGate.php) renvoie un jeton de défi à usage unique au lieu d’exécuter l’outil. L’agent relaie le défi à un humain, puis ré-invoque le même outil avec le jeton émis dans l’argument _confirmation_token. Le jeton lie le nom de l’outil, un nonce aléatoire et une durée de vie (TTL) de 300 secondes. Il ne lie pas les arguments et n’est pas un justificatif d’authentification. En REST, la clé d’API porteuse authentifie toujours la requête, et la même barrière s’exécute dans l’exécuteur d’outils partagé avant l’opération contrôlée. En gRPC, la même barrière s’exécute avant l’opération dispatchée. Le mécanisme de défi et de jeton est identique sur tous les transports.

Outils et points de terminaison

Le tableau documente chaque outil par son nom d’outil enregistré (colonne Symbole) et indique sa classe d’implémentation. Les outils sont regroupés par niveau et par catégorie. Toutes les classes AST et de mutation se trouvent sous src/Tools/Ast et src/Tools/Ast/Mutation ; la classe d’extraction se trouve sous src/Tools/Extraction ; les classes restantes se trouvent sous src/Tools/Core.

Outils de document de base

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
create_pdf	page_size (par défaut A4), orientation (portrait/landscape), title, author ; aucun n’est requis.	Crée un document en mémoire et une page ; définit les métadonnées lorsqu’elles sont fournies.	JSON avec document_id, page_count, page_size, orientation.	Renvoie un résultat d’erreur avec le message du moteur en cas d’échec.	Classe CreatePdfTool. Risque RiskLevel::Caution. Niveau core. Le document_id renvoyé alimente chaque opération ultérieure.
add_page	document_id (requis), taille de page et orientation optionnelles.	Ajoute une page au document.	JSON avec le nouveau nombre de pages.	Résultat d’erreur si document_id est inconnu.	Classe AddPageTool. Risque RiskLevel::Caution. Niveau core.
add_text	document_id (requis), text (requis), position et style optionnels.	Ajoute du texte au document.	Résumé JSON de l’état du document.	Résultat d’erreur si document_id est inconnu.	Classe AddTextTool. Risque RiskLevel::Caution. Niveau core.
add_image	document_id (requis), source (requis : chemin de fichier ou base64), placement optionnel.	Ajoute une image depuis un chemin ou des données base64.	Résumé JSON de l’état du document.	Résultat d’erreur si la source est illisible ou si document_id est inconnu.	Classe AddImageTool. Risque RiskLevel::Caution. Niveau core.
add_table	document_id (requis), html (requis).	Rend une table Hypertext Markup Language (HTML) dans le document.	Résumé JSON de l’état du document.	Résultat d’erreur si le balisage est invalide ou si document_id est inconnu.	Classe AddTableTool. Risque RiskLevel::Caution. Niveau core.
set_font	document_id (requis), family (requis), taille et style optionnels.	Définit la police pour les opérations de texte ultérieures.	Confirmation JSON de la police active.	Résultat d’erreur si la police est inconnue ou si document_id est inconnu.	Classe SetFontTool. Risque RiskLevel::Caution. Niveau core.
output_pdf	document_id (requis), file_path (optionnel), destroy (par défaut true).	Finalise le document ; écrit vers file_path ou renvoie du base64 lorsqu’il est omis ; détruit le document par défaut.	JSON avec file_path et file_size, ou base64 et file_size.	Résultat d’erreur si document_id est inconnu ; échec du confinement du chemin lors d’une écriture hors du répertoire de base.	Classe OutputPdfTool. Risque RiskLevel::ApprovalRequired. Niveau core. L’écriture d’un fichier passe par la barrière de confirmation ; le mode base64 n’y passe pas.
preview_layout	document_id (requis).	Renvoie un résumé de mise en page sans rendre le PDF final.	Résumé JSON de la mise en page.	Résultat d’erreur si document_id est inconnu.	Classe PreviewLayoutTool. Risque RiskLevel::Safe. Niveau core.
parse_pdf	document_id (requis).	Inspecte les métadonnées structurelles : nombre de pages, polices, images, chiffrement et dictionnaire Info.	Métadonnées structurelles JSON.	Résultat d’erreur si le document est mal formé.	Classe ParsePdfTool. Risque RiskLevel::Safe. Niveau core. Enregistré uniquement quand NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED vaut true ou 1.

Outils de diagnostic de base

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
diagnostic.doctor	aucun.	Exécute une vérification d’état et renvoie des diagnostics d’environnement structurés.	Rapport JSON d’environnement.	Résultat d’erreur en cas d’échec d’un contrôle interne.	Classe DiagnosticDoctorTool. Risque RiskLevel::Safe. Niveau core. Ne nécessite ni document ni confirmation.
diagnostic.capabilities	aucun.	Liste les capacités avec leurs informations de niveau et de statut.	Liste JSON des capacités.	Résultat d’erreur en cas d’échec interne.	Classe DiagnosticCapabilitiesTool. Risque RiskLevel::Safe. Niveau core.
diagnostic.inspect	document_id (requis).	Inspecte un PDF et renvoie des métadonnées structurelles.	Métadonnées structurelles JSON.	Résultat d’erreur si document_id est inconnu.	Classe DiagnosticInspectTool. Risque RiskLevel::Safe. Niveau core.
diagnostic.verify	document_id (requis), profil PDF/A ou PDF/UA optionnel.	Vérifie l’intégrité structurelle ; valide optionnellement PDF/A ou PDF/UA en lançant un sous-processus VeraPDF.	Rapport JSON de vérification.	Résultat d’erreur en cas d’échec de sous-processus, de dépassement de délai ou d’entrée surdimensionnée.	Classe DiagnosticVerifyTool. Risque RiskLevel::Caution. Niveau core. L’entrée est plafonnée à 50 mébioctets (Mio).

Outil de code-barres de base

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
generate_barcode	payload (requis), format (par exemple QR Code, DataMatrix).	Génère une matrice bidimensionnelle de modules de code-barres pour la charge utile.	Matrice de modules JSON.	Résultat d’erreur si le format n’est pas pris en charge ou si la charge utile est invalide.	Classe BarcodeTool. Risque RiskLevel::Caution. Niveau core. Le BarcodeTool ne s’enregistre que lorsque le registre d’encodeurs barcode de base est présent dans le nextpdf/core installé ; le nom d’outil enregistré est generate_barcode.

Outils de confidentialité Enterprise

Ils encapsulent les classes de confidentialité Enterprise et s’enregistrent au niveau Enterprise uniquement lorsque ces classes sont chargeables automatiquement. Ils opèrent sur du contenu en texte brut.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
redact_pdf	content (requis), options de détection optionnelles.	Caviarde de manière destructive les informations personnelles identifiables (PII) dans du contenu en texte brut à l’aide du moteur de caviardage Enterprise.	JSON avec le contenu caviardé et un hachage SHA-256.	Résultat d’erreur si les classes Enterprise sont absentes ou si la détection échoue.	Classe RedactPdfTool. Risque RiskLevel::Review. Niveau enterprise.
deidentify_pdf	content (requis), strategy (redact ou suppress).	Applique une stratégie de désidentification systématique au contenu en texte brut à l’aide du désidentifieur Enterprise.	JSON avec le contenu désidentifié.	Résultat d’erreur si les classes Enterprise sont absentes.	Classe DeIdentifyPdfTool. Risque RiskLevel::Review. Niveau enterprise.
zone_redact_pdf	content (requis), zones (page plus liste de rectangles normalisés).	Applique des caviardages de zone basés sur les coordonnées à l’aide du moteur de caviardage Enterprise.	JSON avec le contenu caviardé.	Résultat d’erreur si une zone est invalide ou si les classes Enterprise sont absentes.	Classe ZoneRedactionTool. Risque RiskLevel::Review. Niveau enterprise.

Outils de lecture de l’arbre syntaxique abstrait (AST)

Ils sont fournis avec le serveur, s’enregistrent au niveau Pro et sont contrôlés par NEXTPDF_AST_TOOLS_ENABLED (activé par défaut). Ils sont en lecture seule.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
get_document_ast	pdf_data (requis).	Construit un AST sémantique : un arbre de nœuds complet avec des ancres de citation pour chaque élément structurel.	Arbre de nœuds JSON plus un ETag pour le contrôle de concurrence.	Résultat d’erreur si le document est mal formé.	Classe GetDocumentAstTool. Risque RiskLevel::Safe. Niveau pro.
get_ast_node	pdf_data (requis), node_id (requis).	Récupère un seul nœud AST et tous ses enfants.	Nœud JSON avec ses enfants.	Résultat d’erreur si node_id est inconnu.	Classe GetAstNodeTool. Risque RiskLevel::Safe. Niveau pro.
get_ast_diff	original_pdf_data (requis), modified_pdf_data (requis).	Compare structurellement deux documents à partir de leurs AST sémantiques.	Nœuds ajoutés, supprimés et modifiés au format JSON.	Résultat d’erreur si un document d’entrée est mal formé.	Classe GetAstDiffTool. Risque RiskLevel::Safe. Niveau pro.
search_ast_nodes	pdf_data (requis), filtres optionnels de type, d’index de page et de texte.	Recherche des nœuds AST par type, index de page ou contenu textuel.	Liste plate JSON des nœuds correspondants avec leurs enfants superficiels.	Résultat d’erreur si le document est mal formé.	Classe SearchAstNodesTool. Risque RiskLevel::Safe. Niveau pro.
extract_cited_text	pdf_data (requis), headings_only optionnel.	Extrait des blocs de texte avec des ancres de citation (page, boîte englobante, confiance).	Blocs de texte cités au format JSON.	Résultat d’erreur si le document est mal formé.	Classe ExtractCitedTextTool. Risque RiskLevel::Safe. Niveau pro. Catégorie ast.
extract_cited_tables	pdf_data (requis).	Extrait des blocs de table avec des ancres de citation ; renvoie une matrice de cellules dans l’ordre, ligne par ligne, pour chaque nœud Table.	Matrices de table JSON avec ancres.	Résultat d’erreur si le document est mal formé.	Classe ExtractCitedTablesTool. Risque RiskLevel::Safe. Niveau pro. Catégorie extraction.

Outils de mutation AST

Ils sont fournis avec le serveur, s’enregistrent au niveau Pro et sont contrôlés par NEXTPDF_MUTATION_TOOLS_ENABLED (activé par défaut). Les quatre sont ApprovalRequired et utilisent le contrôle de concurrence optimiste (OCC) via un ETag.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (tous requis).	Applique un lot de mutations de manière atomique ; rejoue le résultat mis en cache pour un idempotency_key répété.	JSON avec le PDF muté et un nouvel ETag.	Conflit OCC lorsque l’ETag est périmé ; erreur de validation si une mutation est mal formée.	Classe ApplyAstMutationsTool. Risque RiskLevel::ApprovalRequired. Niveau pro.
delete_ast_node	pdf_data, node_id, etag (tous requis).	Supprime un nœud en mode superposition (le contenu original est recouvert, pas physiquement supprimé).	JSON avec le PDF modifié et un nouvel ETag.	Conflit OCC lorsque l’ETag est périmé ; erreur si node_id est inconnu.	Classe DeleteAstNodeTool. Risque RiskLevel::ApprovalRequired. Niveau pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (tous requis).	Insère un nouveau nœud comme enfant du parent à la position indiquée.	JSON avec le PDF modifié et un nouvel ETag.	Conflit OCC lorsque l’ETag est périmé ; erreur de validation si un nœud est mal formé.	Classe InsertAstNodeTool. Risque RiskLevel::ApprovalRequired. Niveau pro.
update_ast_node	pdf_data, node_id, etag, updates (tous requis).	Met à jour le contenu textuel d’un nœud.	JSON avec le PDF modifié et un nouvel ETag.	Conflit OCC lorsque l’ETag est périmé ; erreur si node_id est inconnu.	Classe UpdateAstNodeTool. Risque RiskLevel::ApprovalRequired. Niveau pro.

Schéma de requête et de réponse

Le transport gRPC définit le schéma typé du serveur dans le paquet Protocol Buffers nextpdf.connect.v1, dans proto/nextpdf/connect/v1/*.proto. Le service et ses messages constituent les symboles de schéma canoniques.

Service NextPDFConnect

Le service NextPDFConnect expose des RPC unaires et des RPC en streaming serveur. Les symboles de schéma sont les noms de méthode RPC ainsi que les messages de requête et de réponse associés.

RPC	Message de requête	Message de réponse	Forme
Render	RenderRequest	RenderResponse	Unaire. Rendu synchrone sans état.
RenderStream	RenderRequest	RenderChunk (stream)	Streaming serveur. Rendu livré sous forme de fragments ordonnés.
SubmitJob	SubmitJobRequest	JobResponse	Unaire. Soumet une tâche de rendu asynchrone.
GetJobStatus	GetJobStatusRequest	JobResponse	Unaire. Interroge le statut de la tâche.
GetJobResult	GetJobResultRequest	RenderResponse	Unaire. Télécharge un résultat terminé.
GetJobResultStream	GetJobResultRequest	RenderChunk (stream)	Streaming serveur. Télécharge un résultat terminé sous forme de fragments.
CancelJob	CancelJobRequest	JobResponse	Unaire. Annule ou supprime une tâche.
CreateSession	CreateSessionRequest	SessionResponse	Unaire. Crée une session de construction de document.
GetSession	GetSessionRequest	SessionResponse	Unaire. Obtient les métadonnées de la session.
DestroySession	DestroySessionRequest	DestroySessionResponse	Unaire. Détruit une session et son document.
SessionOperation	SessionOperationRequest	SessionResponse	Unaire. Exécute une opération sur un document de session.
SessionRender	SessionRenderRequest	RenderResponse	Unaire. Rend un document de session en PDF.
SessionRenderStream	SessionRenderRequest	RenderChunk (stream)	Streaming serveur. Rend un document de session sous forme de fragments.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unaire. Exécute une opération de capacité contrôlée par niveau.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unaire. Liste les capacités pour le client authentifié.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unaire. Sonde de vivacité.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unaire. Sonde de disponibilité.

Symboles de message

Les messages de requête et de réponse sont les symboles structurels du schéma. Les messages de rendu — RenderRequest, RenderResponse et le RenderChunk en streaming — portent la taille de page, l’orientation, les opérations ordonnées et les octets PDF résultants. Les messages de tâche — SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest et JobResponse — modélisent le cycle de vie de la tâche asynchrone, avec les métadonnées de tâche conservées dans le message JobData. Les messages de session — CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest et SessionRenderRequest — modélisent le cycle de vie de la session avec état, avec les métadonnées de session conservées dans le message SessionData. Les messages de capacité — CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest et GetCapabilitiesResponse — portent l’acheminement et l’introspection des opérations contrôlées par niveau. Les messages système — HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest et ReadinessCheckResponse — portent le statut de vivacité et de disponibilité.

Les fichiers .proto fournis sont le contrat filaire de référence ; la référence du transport gRPC se trouve dans Transport gRPC.

Modèle d’erreur

Le serveur signale les échecs avec le mécanisme d’erreur natif de chaque transport. Chaque transport préserve la même condition logique ; seul l’encodage diffère.

MCP

Les erreurs MCP sont des objets d’erreur JSON-RPC 2.0. Une méthode inconnue renvoie method-not-found (-32601) ; un message qui n’est pas un JSON-RPC valide renvoie invalid-request (-32600) ; une entrée impossible à analyser renvoie parse-error (-32700). Un outil qui échoue renvoie une réponse JSON-RPC réussie dont le contenu marque l’erreur, plutôt qu’une erreur de transport, afin que l’agent puisse lire le message. Un défi de confirmation pour un outil ApprovalRequired est également une réponse réussie, pas une erreur.

REST

REST utilise les codes de statut Hypertext Transfer Protocol (HTTP) avec la sémantique définie par RFC 9110. Un 200 transporte le résultat ; un 400 est renvoyé lorsqu’un champ de la requête ne passe pas la validation de format ; un 401 est renvoyé lorsqu’aucune clé d’API valide n’est présentée et porte un en-tête de défi WWW-Authenticate: Bearer ; un 403 est renvoyé lorsque le niveau d’une clé valide n’est pas autorisé à effectuer l’opération ; un 404 est renvoyé lorsqu’une route contrôlée par le niveau n’est pas enregistrée parce que son package est absent. Les corps d’erreur lisibles par machine sont des documents Problem Details conformes à RFC 9457, servis avec le type de média application/problem+json et un Uniform Resource Identifier (URI) type stable pour chaque condition. Les échecs de validation par champ sont listés dans le corps. Comme mesure de durcissement contre la traversée de chemin, un document_id qui ne correspond pas au motif doc_[a-f0-9]{24} est rejeté avec 400 avant l’exécution de l’outil. Le pipeline de middleware REST et la table de routage sont documentés dans Transport REST.

gRPC

gRPC utilise les codes de statut gRPC standard. Un jeton manquant, mal formé, inconnu, désactivé ou expiré fait échouer l’appel avec UNAUTHENTICATED plutôt qu’avec un statut HTTP. Le détail d’erreur enrichi reflète la forme Problem Details de REST et est porté dans les détails de statut gRPC, de sorte que l’URI type d’erreur reste cohérent sur tous les transports.

Voir aussi : RFC 9110 (HTTP Semantics) pour la sémantique des codes de statut et RFC 9457 (Problem Details for HTTP APIs) pour le format du corps d’erreur.

• RFC 9110 : https://www.rfc-editor.org/rfc/rfc9110
• RFC 9457 : https://www.rfc-editor.org/rfc/rfc9457

Limites de débit et quotas

Le transport REST applique une limitation de débit par adresse IP (Internet Protocol) et par client dans son pipeline de middleware, ainsi que des limites de taille de corps et de charge utile par niveau, plus un délai d’expiration par requête. Les plafonds pertinents sont des valeurs de configuration, pas des constantes codées en dur :

• Les plafonds de charge utile par niveau (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) et les délais d’expiration correspondants s’appliquent en REST selon le niveau de la clé authentifiée. Voir Configuration.
• Le magasin de documents en mémoire est borné par max_documents (par défaut 50) et document_ttl (par défaut 1800 secondes).
• L’état de limitation de débit et d’idempotence est par worker, sauf si NEXTPDF_REDIS_HOST est configuré pour un magasin partagé. Voir Déploiement.

Lorsque les magasins de limitation de débit et d’idempotence sont partagés, les soumissions de tâche asynchrone répétées à l’identique sont dédupliquées par la idempotency_key. Le transport MCP traite une requête à la fois sur des pipes et déduplique un id de requête répété à partir d’un tampon de 64 entrées au lieu d’appliquer des limites de débit réseau.

Notes de développement

• Lis les noms d’outils, les classes et les niveaux de risque depuis le code source sous src/Tools/ ; ne suppose pas un total fixe. Interroge le serveur en cours d’exécution pour obtenir le décompte faisant autorité, comme indiqué dans Catalogue d’outils.
• Régénère les stubs client gRPC depuis les fichiers proto/nextpdf/connect/v1/*.proto fournis ; le paquet et l’espace de noms sont nextpdf.connect.v1. Ne modifie pas manuellement les classes de message générées.
• Un outil ApprovalRequired répond par un défi de confirmation au premier appel. Prévois le chemin de nouvelle tentative — relaie le défi, puis ré-invoque avec _confirmation_token — avant de livrer une intégration qui pilote output_pdf ou tout outil de mutation.
• Une route ou une capacité contrôlée par niveau qui n’est pas installée n’est pas un échec d’authentification : REST renvoie 404 pour une route absente, et le ExecuteCapability gRPC signale l’opération comme indisponible. Traite un niveau Pro ou Enterprise absent comme un fonctionnement attendu, pas comme une faute.
• Garde les clés d’API hors de la gestion de version ; monte-les depuis un fichier de secret et préfère le magasin de clés sur fichier avec rechargement à chaud, pour qu’une rotation ne nécessite aucun redémarrage. Voir Sécurité et exploitation.

Voir aussi

• Guide du développeur — architecture, cycle de vie, points d’extension et checklist de tests
• Catalogue d’outils — l’ensemble vérifié des outils de base et le décompte d’exécution
• Niveaux de risque HITL — le modèle de risque et le défi de confirmation
• Transport MCP · Transport REST · Transport gRPC — les détails filaires par transport
• Sécurité et exploitation — authentification, sécurité du transport et modèle de menace