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) :
- 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. - Cochez les domaines accessibles (voir ci-dessous).
- 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).
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 |
Les deux derniers domaines 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.
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.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é.