Documentation · Get started

Quickstart. First call in five minutes.

Sign up, mint a sandbox key, install an SDK, and run an extraction. No demo data — you'll send a real PDF and parse a real JSON response.

← Back to documentation

Prerequisites

A Cogneris tenant — sign up at app.cogneris.ai; sandbox is free and seeded with 100 pages.
A runtime — .NET 8+, Node 18+, Python 3.10+, Go 1.21+ or Java 17+.
A PDF to test — your own, or grab sample-invoice.pdf from the sandbox dashboard.

1. Get a sandbox key

In the dashboard, open Settings → API keys → Create. Pick scope sandbox.read sandbox.write and copy the key once — it's only shown at creation. Keys are tenant-scoped and rotate via Authentication.

~/.zshrc or .env

# Export it once
export COGNERIS_KEY="flx_sk_sb_…"
export COGNERIS_BASE_URL="https://api.sandbox.cogneris.ai"

2. Install an SDK

Pick the one that matches your stack — or skip to cURL.

install

# .NET
dotnet add package Cogneris.Sdk

# Node.js
npm i @cogneris/sdk

# Python
pip install Cogneris

# Go
go get github.com/cogneris-ai/cogneris-go

# Java
# Maven
implementation "ai.cogneris:cogneris-sdk:1.0.0"

3. Send your first PDF

Extract against the shipped invoice template — same payload across SDKs.

Node.js

import { Cogneris } from "@cogneris/sdk";
import fs from "node:fs";

const client = new Cogneris({ apiKey: process.env.COGNERIS_KEY });

const result = await client.extract.create({
  template: "invoice",
  file:     fs.createReadStream("./sample-invoice.pdf"),
});

console.log(result.data.vendor_name.value);
console.log(result.data.total_amount.value);

Python

from Cogneris import Cogneris

client = Cogneris()  # picks COGNERIS_KEY from env

with open("sample-invoice.pdf", "rb") as f:
    result = client.extract.create(template="invoice", file=f)

print(result.data["vendor_name"]["value"])
print(result.data["total_amount"]["value"])

cURL

curl -X POST "$COGNERIS_BASE_URL/v1/extract" \
  -H "Authorization: Bearer $COGNERIS_KEY" \
  -F "template=invoice" \
  -F "file=@./sample-invoice.pdf"

4. Read the response

The wrapper is the same on every endpoint: data for the payload, meta for trace + audit URL, has_errors for fast failure checks. Every field is { value, confidence, bbox? } — not a bare string — so you can route by confidence without reparsing.

200 OK · trimmed

{
  "data": {
    "vendor_name":  { "value": "Acme Industries Ltd.", "confidence": 0.98 },
    "total_amount": { "value": 12480.50,           "confidence": 0.99 }
  },
  "meta": { "audit_url": "https://app.cogneris.ai/audit/ext_01J9MR3K" },
  "has_errors": false
}

Open the audit_url in your browser to see the prompts, retrieved passages and reasoning that produced each value. This is the same trace your auditors can inspect later.

5. Go async

Sync is capped at 25 pages. For larger files or batches, post to /v1/extract/async — you get a job_id back and a webhook delivery when the run finishes. The shape of the final payload is identical, so step 4 still applies.

cURL · async

curl -X POST "$COGNERIS_BASE_URL/v1/extract/async" \
  -H "Authorization: Bearer $COGNERIS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "template=contract" \
  -F "file=@./500-page-msa.pdf" \
  -F "webhook_url=https://hooks.example.com/Cogneris"

Troubleshooting

SymptomFix

401Wrong base URL or expired key — sandbox keys start with flx_sk_sb_, prod with flx_sk_pr_.

413File over 100 MB or 25 pages — switch to /v1/extract/async.

422Document unreadable — encrypted PDF, blank pages or zero text + zero OCR.

429Sandbox quota is 60 req/min; bump in prod, or wait for Retry-After.

Next: Authentication

Key scopes, rotation and signing webhook deliveries.

Read Authentication