Accessing a Pipeline via API
A pipeline can be invoked directly by an external system, without going through the web interface, using an API key.
Generating a key
From Manager → Settings → API Keys (API keys — write permission):
- Generate a key — it is prefixed
hnk_, remains viewable at any time (unlike a "shown only once" token), and can either expire on a set date or never expire. - Tick the accessible domains (see below).
- Assign it to one or more specific pipelines: the key can only start analyses on the pipelines explicitly assigned to it (any other attempt fails).
Each key is internally attached to a dedicated service account, so that jobs launched via the API remain attributable and traceable just like any other job. That account can never sign in to the web interface — neither by password nor by Microsoft SSO — and does not appear in Admin → Users: it is managed solely from this screen.
Accessible domains
A key reaches only the domains you tick. Every other API route is refused to it, whatever its role: this restriction adds to the permissions, it does not replace them.
| Domain | What it opens | Permission to give the service account |
|---|---|---|
| Annotation | submit a document, track and download the result | (none) |
| Chat | conversations and messages of a chat pipeline | (none) |
| Correspondences | read and write correspondence tables | Correspondence data — read |
| Knowledge base | list, add, delete documents, start indexing | Knowledge bases — read |
The last two domains require a role: tick the domain and assign the key a user profile carrying the role shown (Admin → Profiles). A robot spanning several domains needs a profile bundling the matching roles — an account holds only one plain role at a time.
If you tick a domain without the role it needs, saving is refused and names the missing role, rather than creating a key that would fail on its first call.
Keys created before domains existed keep exactly their original reach — Annotation and Chat. Add the other domains by hand if needed.
Available calls
With the header Authorization: Bearer hnk_...:
POST /api/jobs— submits a document for analysis (multipart upload: file, pipeline ID, optional support documents).POST /api/jobs/from-url— submits a document via a link (shared Google Docs/Slides) instead of a direct upload.GET /api/jobs/{id}— checks the status of an ongoing analysis.GET /api/jobs/{id}/download— downloads the annotated document once the analysis is complete.POST /api/jobs/{id}/cancel— cancels an ongoing analysis.
The pipeline editor offers an "API" panel that automatically generates ready-to-copy code (Python, JavaScript, PHP, VB.NET) illustrating these calls, with the current pipeline's ID already filled in.