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):

1. 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.
2. Tick the accessible domains (see below).
3. 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). The list shows for each pipeline whether it is exposed as an API and/or over MCP, and flags a pipeline that is assigned but not exposed.

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
MCP server	call the assigned pipelines from an AI assistant (see Pipeline as an MCP server)	(none)

The Correspondences and Knowledge base 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. The MCP server domain is never ticked by default, on any key.

Exposing the pipeline

Assigning a pipeline to a key is not enough: it must also be exposed. In the pipeline editor, open ⚙ Pipeline settings and tick Expose as an API (the pipeline must be active). Until it is ticked, the API answers 403 This pipeline is not exposed as an API to a key that is nonetheless assigned to it; unticking it cuts access immediately, for every key.

Pipelines already assigned to a key when this option appeared were exposed automatically, so that no existing integration was cut off.

Exposure as an MCP server is a separate checkbox (see Pipeline as an MCP server).

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.
• GET /api/jobs/{id}/extraction — for an extraction portfolio, returns the extracted JSON (see JSON output). Such a portfolio produces no document to download and also accepts images (.jpg, .png, .tif, .tiff, .bmp) as input.
• 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.

GET /api/teams/my-pipelines lists, for a key, the pipelines it can actually call (assigned, active and exposed).

Call credits (cloud edition)

On the hosted service, pipeline calls made through an API key or an MCP server use call credits, on top of the per-seat subscription. The web interface and Teams stay included in the subscription: every user acts there under their own account, which takes a seat.

• 1 call = 1 credit, whatever the size of the document: a submitted document (POST /api/jobs, /api/jobs/from-url, MCP tool submit_document) or a message sent to a chat pipeline (POST /api/conversations/{id}/messages, MCP tool ask).
• Free of charge: status polling, download, cancellation, Designer trials, and the Correspondences and Knowledge base domains.
• A call that fails or is cancelled is not counted. While it runs, it reserves its credit: two simultaneous calls cannot share the last one.
• With an exhausted balance, the call is refused with 402 and a stable code, so a robot can tell this case apart from other errors:

{"detail": "API/MCP call credits exhausted: top them up from Organization → Subscription.", "code": "credits_exhausted"}

Over MCP, the tool returns an error whose text starts with [credits_exhausted].

Credits are bought in volume-discounted packs from Organization → Subscription → Top up (Subscription — write permission, terms of sale to accept): the invoice is issued immediately and the credits are available at once. They remain valid for 3 years and are used oldest first. The same page shows the balance, calls in progress, this month's usage, the next expiry and the history. Subscription administrators receive an email when the balance gets low, then when it runs out.

These credits do not exist in the on-premise edition: calls there are unlimited.