Document processing, metered per page.

Quickstart

Create a key under Account → API keys (pick Sandbox for a dxk_test_ key that never bills, or Live for dxk_live_). Then: upload, create a job, poll, download. Three calls.

# 1. Upload
curl -s https://docaxo.com/api/v1/files \
  -H "Authorization: Bearer $DOCAXO_API_KEY" \
  -F "[email protected]"
# → {"id":"f_…","object":"file","page_count":3,"status":"ready",…}

# 2. Start a job (safe to retry thanks to Idempotency-Key)
curl -s https://docaxo.com/api/v1/jobs \
  -H "Authorization: Bearer $DOCAXO_API_KEY" \
  -H "Idempotency-Key: order-42-ocr" \
  -H "Content-Type: application/json" \
  -d "{\"operation\":\"ocr\",\"file_id\":\"$FILE_ID\",\"options\":{\"mode\":\"base\"}}"
# → 202 {"id":"…","status":"queued","credits":{"billed":true,"pages_estimated":3},…}

# 3. Poll, then download
curl -s "https://docaxo.com/api/v1/jobs/$JOB_ID" -H "Authorization: Bearer $DOCAXO_API_KEY"
curl -sL "https://docaxo.com/api/v1/jobs/$JOB_ID/result?format=json" \
  -H "Authorization: Bearer $DOCAXO_API_KEY" -o blocks.json

Prefer push over polling? Register a webhook and wait for job.succeeded. The OpenAPI document lives at /api/v1/openapi.json.

Authentication

Send your key as a Bearer token: Authorization: Bearer dxk_live_…. Browser cookies are never accepted on /api/v1; a request without a key gets 401 authentication_required.

• Prefix decides the mode. dxk_live_ keys process and bill; dxk_test_ keys use the sandbox. Files, jobs and webhooks are partitioned per mode — a live key cannot see sandbox objects (403 mode_mismatch).
• Plan. Live keys need the API Starter plan, otherwise 403 plan_required with an upgrade_url. Sandbox keys work on every plan.
• Scopes. documents:read, documents:write, jobs:read, jobs:write, usage:read, webhooks:manage. A missing scope is 403 insufficient_scope.
• Rotation. Rotate from the account page; the old key keeps working for the grace period you choose. GET /api/v1/account tells you which key, plan and limits a request is running under.

Files

POST /api/v1/files accepts a multipart/form-data body with a single file part (PDF, DOCX, XLSX, CSV, JPEG, PNG, WebP; the bytes must match the declared type). The response includes page_count — that is what a job will reserve credits for — and the file is ready immediately.

For large uploads send JSON {filename, content_type, size_bytes} instead: you get a presigned PUT URL; upload the bytes, then call POST /files/{id}/complete. Presigned URLs need the S3 object store — on a local MinIO-less setup the API answers 501 presigned_unavailable, so fall back to multipart.

Jobs & operations

POST /api/v1/jobs with {operation, file_id | file_ids, options, metadata} returns 202 and a job in queued. Poll GET /jobs/{id} until succeeded, failed or cancelled, then fetch GET /jobs/{id}/result (format=download streams the file, json returns OCR blocks, url gives a short-lived presigned link). metadata (≤ 20 string keys) is echoed back on the job and in webhooks.

Operations map one-to-one onto real worker job kinds. Anything without a handler — including convert targets pptx, png, html, txt — answers 422 operation_unsupported with a reason; we never return a fake result. GET /api/v1/operations serves this table as JSON.

POST /jobs/{id}/cancel stops a queued job immediately (its reservation is released) and asks a running one to stop at the next checkpoint. Per-job wall-clock timeouts and page caps (page_limit_exceeded) follow your plan; see GET /api/v1/account.

Idempotency

Network failures happen between “request sent” and “response read”. Send an Idempotency-Key header on POST /api/v1/jobs and retries are safe: the stored response is replayed with Idempotent-Replayed: true and no second job or reservation is created. Keys are scoped to the API key and kept for 24 hours.

POST /api/v1/jobs
Idempotency-Key: order-42-ocr        # ≤ 255 chars, scoped to the API key, kept 24h

# first call  → 202 + job
# retry       → 202 + the *same* job, header Idempotent-Replayed: true
# same key, different body → 422 idempotency_key_reused
# key still in flight      → 409 idempotency_in_progress

Webhooks

Register up to 10 HTTPS endpoints per mode with POST /api/v1/webhooks {url, events?, description?}. The response contains the signing secret (whsec_…) exactly once. POST /webhooks/{id}/test sends a signed webhook.test synchronously so you can wire things up before the first real job.

POST https://example.com/docaxo
Docaxo-Event: job.succeeded
Docaxo-Signature: t=1757700000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Content-Type: application/json

{
  "id": "evt_01J7…",
  "object": "event",
  "type": "job.succeeded",
  "api_version": "2026-09-01",
  "livemode": true,
  "created_at": "2026-09-12T18:00:00+00:00",
  "data": {
    "object": {
      "id": "…", "object": "job", "operation": "ocr", "status": "succeeded",
      "metadata": { "order": "42" },
      "result": { "download_url": "https://docaxo.com/api/v1/jobs/…/result", "pages_processed": 3 }
    }
  }
}

Verify the signature

Docaxo-Signature is t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(secret, `${t}.${raw body}`). Compute it over the raw bytes (before JSON parsing), compare in constant time, and reject timestamps older than 5 minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyDocaxoSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; // replay window
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

// Express: app.post("/docaxo", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyDocaxoSignature(req.body.toString("utf8"), req.get("Docaxo-Signature"), process.env.WHSEC)) return res.sendStatus(400);
//   const event = JSON.parse(req.body); … ; res.sendStatus(200);
// });

Retries

Any non-2xx response or a timeout (10 s) is retried with backoff: 1m → 5m → 30m → 2h → 12h — six attempts in total. Event ids are stable across retries, so deduplicate on id. After 30 consecutive failures an endpoint is disabled (disabled_reason); re-enable it with PATCH /webhooks/{id} {enabled: true}. Every attempt is visible at GET /webhooks/{id}/deliveries.

Rate limits

Each key has a token bucket of 60 requests per minute (sandbox: 30) and may have 2 jobs queued or running at once (sandbox: 2). Exceeding either answers 429 with rate_limited or concurrency_limit; back off for Retry-After seconds. Limits are per key, so give each integration its own. The concurrency figure is part of the API Starter plan; the effective limits for your key are always returned by GET /account → limits.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3

{"error":{"type":"rate_limit_error","code":"rate_limited",…}}

Errors

Every error is JSON with one envelope. type groups codes for coarse handling, code is stable and machine-readable, doc_url deep-links into this page and request_id matches the X-Request-Id header. Validation errors add param; billing errors add pages/remaining.

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_5f1c…

{
  "error": {
    "type": "invalid_request_error",
    "code": "operation_unsupported",
    "message": "Operation 'watermark' is not available through the API",
    "doc_url": "https://docaxo.com/api-docs#error-operation_unsupported",
    "request_id": "req_5f1c…",
    "param": "operation"
  }
}

Retry 429, 503 and network errors with exponential backoff and the same Idempotency-Key. Do not retry 4xx codes without changing the request.

Pricing & credits

Sandbox vs live

Endpoint reference

Static list — the live spec is served at https://docaxo.com/api/v1/openapi.json and Swagger UI at https://docaxo.com/api/v1/docs.