Skip to main content

API Examples

Every example calls the production API in Europe, https://api-eu.cogneris.ai, where new tenants are created. If your tenant lives in the United States, use https://api-us.cogneris.ai instead — a key works only in the region of its tenant.

The examples read the key from the COGNERIS_API_KEY environment variable. Keep it there, never in source code:

export COGNERIS_API_KEY="<your API key>"
Synchronous /Document/* calls need a production key

POST /Document/extraction, POST /Document/classifier and the other /Document/* endpoints accept only a production key (xtkt_live_). A sandbox key (xtkt_test_) is refused with 403 and the code environment.sandbox_route_unavailable. With a sandbox key, use the asynchronous job flow below.

Extract the fields of a document​

POST /Document/extraction takes one file in the file form field. The platform picks the template configured for your tenant from the document itself, so there is no template or schema parameter.

curl -X POST "https://api-eu.cogneris.ai/Document/extraction" \
  -H "Authorization: Bearer $COGNERIS_API_KEY" \
  -F "file=@./invoice.pdf"

The same call in Python and Node.js:

import os
import requests

with open("invoice.pdf", "rb") as document:
    response = requests.post(
        "https://api-eu.cogneris.ai/Document/extraction",
        headers={"Authorization": f"Bearer {os.environ['COGNERIS_API_KEY']}"},
        files={"file": ("invoice.pdf", document, "application/pdf")},
        timeout=120,
    )

envelope = response.json()
if not response.ok or envelope.get("hasErrors"):
    raise RuntimeError(f"extraction failed with status {response.status_code}")
print(envelope["data"]["metadata"])
import fs from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await fs.readFile("./invoice.pdf")]), "invoice.pdf");

const response = await fetch("https://api-eu.cogneris.ai/Document/extraction", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.COGNERIS_API_KEY}` },
  body: form,
});

const envelope = JSON.parse(await response.text());
if (!response.ok || envelope.hasErrors) {
  throw new Error(`extraction failed with status ${response.status}`);
}
console.log(envelope.data.metadata);

Optional: send ComplementaryPrompt as a second form field to ask for something extra, for example -F "ComplementaryPrompt=Also return the payment terms.". See POST /Document/extraction for every field of the answer.

Classify documents​

POST /Document/classifier takes the files form field. Repeat it to classify several documents in one call; the answer has one entry per file in data.results, each with fileName, documentType and confidence.

curl -X POST "https://api-eu.cogneris.ai/Document/classifier" \
  -H "Authorization: Bearer $COGNERIS_API_KEY" \
  -F "files=@./invoice.pdf" \
  -F "files=@./id-card.jpg"

See POST /Document/classifier.

Asynchronous job flow​

For long documents, or when you work with a sandbox key, upload the file once and submit a job that references it. These routes accept both production and sandbox keys. A sandbox job does not consume credits; on a sandbox key, Extraction runs only without a templateId.

1. Upload the document. The answer carries an artifact:// reference in data.reference, valid for 7 days.

curl -X POST "https://api-eu.cogneris.ai/api/v1/artifacts" \
  -H "Authorization: Bearer $COGNERIS_API_KEY" \
  -F "file=@./invoice.pdf"

2. Submit the job. operation is one of Extraction, Classification, ZeroShot, Crop, Split or Facematch. Send a stable Idempotency-Key so a retried submit returns the same job instead of queuing a second one.

curl -X POST "https://api-eu.cogneris.ai/api/v1/document-jobs" \
  -H "Authorization: Bearer $COGNERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-0001" \
  -d '{"operation":"Extraction","inputReference":"<data.reference from step 1>"}'

The answer is 202 with data.jobId, data.status and a Retry-After hint.

3. Poll the job until data.status is Succeeded, Failed or Cancelled, waiting the Retry-After interval between calls (or register a webhook endpoint, described in the API reference, and let the completion event come to you).

curl "https://api-eu.cogneris.ai/api/v1/document-jobs/<jobId>" \
  -H "Authorization: Bearer $COGNERIS_API_KEY"

4. Download the result. A succeeded job carries data.outputReference; read it back as bytes:

curl -G "https://api-eu.cogneris.ai/api/v1/artifacts/content" \
  --data-urlencode "reference=<data.outputReference>" \
  -H "Authorization: Bearer $COGNERIS_API_KEY"

Response parsing​

Successful answers share one envelope: data for the payload, meta for the status and messages, and hasErrors for a fast failure check. Errors raised before your request is processed — a missing or invalid key (401), the rate limit (429) — arrive as application/problem+json with a stable code; branch on it.

caution

Some Cogneris backend responses are returned with Content-Type: text/plain while the body contains JSON. Read the body as text and parse it as JSON, as the examples above do, even when the content type is not application/json.

More examples​

Ready-to-run SDK examples (TypeScript, Python, C#, Java), a CLI and a Postman collection are in cogneris-api-examples.