Accès au pipeline par API

Un pipeline peut être invoqué directement par un système externe, sans passer par l'interface web, via une clé API.

Générer une clé

Depuis Manager → Paramètres → Clés API (permission Clés API — écriture) :

1. Générez une clé — elle est préfixée hnk_, reste consultable à tout moment (contrairement à un jeton « affiché une seule fois »), et peut avoir une date d'expiration ou ne jamais expirer.
2. Cochez les domaines accessibles (voir ci-dessous).
3. Assignez-lui un ou plusieurs pipelines précis : la clé ne peut lancer des analyses que sur les pipelines qui lui sont explicitement assignés (toute autre tentative échoue). La liste indique pour chaque pipeline s'il est exposé API et/ou MCP, et signale un pipeline assigné mais non exposé.

Chaque clé est rattachée en interne à un compte de service dédié, pour que les jobs lancés via l'API restent attribuables et traçables comme n'importe quel autre job. Ce compte ne peut jamais se connecter à l'interface web — ni par mot de passe, ni par SSO Microsoft — et n'apparaît pas dans Admin → Utilisateurs : il se gère uniquement depuis cet écran.

Domaines accessibles

Une clé n'atteint que les domaines cochés. Toute autre route de l'API lui est refusée, quelles que soient ses permissions : c'est une restriction qui s'ajoute aux droits, elle ne les remplace pas.

Domaine	Ce qu'il ouvre	Permission à donner au compte de service
Annotation	soumettre un document, suivre et télécharger le résultat	(aucune)
Chat	conversations et messages d'un pipeline de chat	(aucune)
Correspondances	lire et écrire dans les tables de correspondances	Données de correspondances — lecture
Base documentaire	lister, ajouter, supprimer des documents, lancer une indexation	Bases de connaissances — lecture
Serveur MCP	appeler les pipelines assignés depuis un assistant IA (voir Pipeline comme serveur MCP)	(aucune)

Les domaines Correspondances et Base documentaire exigent une permission : cochez le domaine et attribuez à la clé un groupe qui la porte (voir Groupes et profils). Un robot couvrant plusieurs domaines reçoit un groupe réunissant les profils correspondants — le groupe étant justement fait pour cela, il n'y a rien de spécifique aux machines à prévoir.

Si vous cochez un domaine sans la permission nécessaire, l'enregistrement est refusé en vous indiquant celle qui manque, plutôt que de créer une clé qui échouerait au premier appel.

Les clés créées avant l'apparition des domaines conservent exactement leur portée d'origine — Annotation et Chat. Ajoutez-leur les autres domaines à la main si nécessaire. Le domaine Serveur MCP n'est jamais coché par défaut, sur aucune clé.

Exposer le pipeline

Assigner un pipeline à une clé ne suffit pas : il faut aussi l'exposer. Dans l'éditeur de pipeline, ouvrez ⚙ Paramètres du pipeline et cochez Exposer comme API (pipeline actif). Tant que la case n'est pas cochée, l'API répond 403 Ce pipeline n'est pas exposé comme API à une clé qui lui est pourtant assignée ; décocher la case coupe l'accès immédiatement, pour toutes les clés.

Les pipelines déjà assignés à une clé au moment de l'apparition de cette option ont été exposés d'office, pour ne couper aucune intégration existante.

L'exposition comme serveur MCP est une case distincte (voir Pipeline comme serveur MCP).

Appels disponibles

Avec l'en-tête Authorization: Bearer hnk_... :

• POST /api/jobs — soumet un document à analyser (upload multipart : fichier, identifiant du pipeline, documents supports éventuels).
• POST /api/jobs/from-url — soumet un document via un lien (Google Docs/Slides partagé) plutôt qu'un upload direct.
• GET /api/jobs/{id} — consulte le statut d'une analyse en cours.
• GET /api/jobs/{id}/download — télécharge le document annoté une fois l'analyse terminée.
• GET /api/jobs/{id}/extraction — pour un portfolio d'extraction, renvoie le JSON extrait (voir Sortie JSON). Un tel portfolio ne produit pas de document à télécharger et accepte aussi les images (.jpg, .png, .tif, .tiff, .bmp) en entrée.
• POST /api/jobs/{id}/cancel — annule une analyse en cours.

L'éditeur de pipeline propose un panneau « API » qui génère automatiquement du code prêt à copier (Python, JavaScript, PHP, VB.NET) illustrant ces appels avec l'identifiant du pipeline courant déjà renseigné.

GET /api/teams/my-pipelines liste, pour une clé, les pipelines qu'elle peut effectivement appeler (assignés, actifs et exposés).

Crédits d'appels (édition cloud)

Sur le service hébergé, les appels de pipelines faits par clé API ou par serveur MCP consomment des crédits d'appels, en plus de l'abonnement au siège. L'interface web et Teams restent inclus dans l'abonnement : chaque utilisateur y agit sous son propre compte, qui occupe un siège.

• 1 appel = 1 crédit, quel que soit le volume du document : un document soumis (POST /api/jobs, /api/jobs/from-url, outil MCP submit_document) ou un message envoyé à un pipeline de chat (POST /api/conversations/{id}/messages, outil MCP ask).
• Ne consomment rien : le suivi de statut, le téléchargement, l'annulation, les essais du Designer, et les domaines Correspondances et Base documentaire.
• Un appel qui échoue ou qui est annulé n'est pas décompté. Pendant son traitement, il réserve son crédit : deux appels simultanés ne peuvent pas se partager le dernier.
• À solde épuisé, l'appel est refusé avec 402 et un code stable, pour qu'un robot distingue ce cas des autres erreurs :

{"detail": "Crédits d'appels API/MCP épuisés : rechargez-les depuis Organisation → Abonnement.", "code": "credits_exhausted"}

Par MCP, l'outil renvoie une erreur dont le texte commence par [credits_exhausted].

Les crédits s'achètent par packs dégressifs depuis Organisation → Abonnement → Recharger (permission Abonnement — écriture, acceptation des CGV) : la facture est émise immédiatement et les crédits sont disponibles aussitôt. Ils restent valables 3 ans et se consomment du plus ancien au plus récent. La même page montre le solde, les appels en cours, la consommation du mois, la prochaine expiration et l'historique. Les administrateurs de l'abonnement reçoivent un email quand le solde devient bas, puis quand il est épuisé.

Ces crédits n'existent pas dans l'édition on-premise : les appels y sont illimités.