Introduction

anyformat API v3 is the current stable major. It runs the same extraction engine as v2 behind a smaller, flatter surface. Three resources cover it: workflows, document packets, and runs. Coming from v2? The migration guide maps every v2 path to its v3 successor. API v2 is retired and answers 410 Gone.

Base URL

https://api.anyformat.ai/v3/

All endpoint paths require a trailing slash. Requests without one receive a 307 Temporary Redirect, which preserves the request method and body.

Authentication

All endpoints require an API key, passed as a Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.anyformat.ai/v3/workflows/

See Authentication to create and manage keys.

Resource model

Resource	What it is	Identifier
Workflow	The extraction template: a typed graph of nodes. The node types are parse, extract, classify, splitter, validate, if_else, slack_alert, edit and knowledge. See Nodes and Node schemas.	`workflow_id`
Document packet	The unit a workflow runs on: one or more files treated as a single document. Uploading creates one.	`document_packet_id`
Run	One execution attempt of a workflow against a packet. One packet can have many runs.	`run_id`

All identifiers are hyphenated UUIDs, such as 069dcc2c-e14c-7606-8000-2ee4fb17b4e1. Path parameters are always snake_case: workflow_id, document_packet_id, run_id. The typical flow:

Create a workflow (or build it visually in the dashboard).
Upload and run a document in one call. The response carries a run_id.
Get the run until status is processed; the results envelope is inline on the same response.

Pagination

Every list endpoint is keyset-paginated and returns the same page shape:

{
  "items": [ ... ],
  "next_cursor": "eyJjcmVhdGVkX2F0Ijoi..."
}

?limit= sets the page size. The default is 20 and the maximum is 100. A larger value returns 400; the API does not clamp it.
?cursor= takes the opaque next_cursor token from the previous page.
Iterate by following next_cursor until it is null.
Sort order is fixed at newest-first (-created_at, -id).

v3 returns no totals, counts, or page numbers. A count over a growing collection is stale the moment it is computed. List endpoints also reject an unknown query parameter with 400 rather than ignoring it, so a typo like ?pagesize= fails loudly.

Idempotency

The POSTs that create packets or trigger runs accept an optional Idempotency-Key header. The value is any unique string you choose, such as a UUID.

Retrying a request with the same key replays the original response. The API creates no duplicate packet, and triggers and bills no second extraction or eval. Use it to make network-timeout retries safe. Reusing a key with a different request body returns 422 IDEMPOTENCY_KEY_REUSED. A key binds to the first request it saw; send a fresh key for a genuinely new request.

curl -X POST 'https://api.anyformat.ai/v3/document-packets/069dcc2c-e14c-7606-8000-2ee4fb17b4e1/run/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: 5f2b6c3e-8a1d-4f7e-9c0b-1a2b3c4d5e6f'

Rate limits

Submission endpoints have a stricter limit, and so does downloading a split, which renders a document on every request. Everything else shares a higher general limit. Each tier counts separately.

Tier	v3 endpoints	Limit
Submission	Every endpoint that starts work or asks a question: `POST /v3/workflows/{id}/upload/`, `POST /v3/workflows/{id}/upload/run/`, `POST /v3/workflows/{id}/upload/from-url/`, `POST /v3/workflows/{id}/dataset/upload/`, `POST /v3/workflows/{id}/evals/`, `POST /v3/workflows/{id}/knowledge/ask`, `POST /v3/document-packets/{id}/run/`, `POST /v3/parse/`, `POST /v3/parse/from-url/`	60 requests/min
Download	`GET /v3/splits/{split_id}/pdf/`	60 requests/min
General	Reading and editing: workflows, runs, document packets, versions, evals results	600 requests/min

Exceeding a limit returns 429 Too Many Requests; wait for the number of seconds in the Retry-After header. Every response carries x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset for the tier that applies.

Response headers

Every /v3/ response is stamped with the API version:

X-API-Version: 3.0.0

v3 responses carry no Deprecation or Sunset headers. A version on the retirement path would add them, per RFC 8594, so alerting on Sunset catches a future retirement early.

Compression

Send Accept-Encoding: gzip and JSON responses over 1 KB come back gzip-compressed, with Content-Encoding: gzip. A run’s results compress about 4x, so a large run downloads faster. Without the header, you get the same response uncompressed. The SDKs, the CLI, Python requests and httpx, and JavaScript fetch send the header and decompress for you. Some clients need it set by hand:

curl --compressed https://api.anyformat.ai/v3/runs/$RUN_ID/ \
  -H "Authorization: Bearer $ANYFORMAT_API_KEY"

import gzip, json, urllib.request

request = urllib.request.Request(
    f"https://api.anyformat.ai/v3/runs/{run_id}/",
    headers={"Authorization": f"Bearer {api_key}", "Accept-Encoding": "gzip"},
)
with urllib.request.urlopen(request) as response:
    body = response.read()
    if response.headers.get("Content-Encoding") == "gzip":
        body = gzip.decompress(body)
run = json.loads(body)

HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.anyformat.ai/v3/runs/" + runId + "/"))
    .header("Authorization", "Bearer " + apiKey)
    .header("Accept-Encoding", "gzip")
    .build();
HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
boolean gzipped = response.headers().firstValue("Content-Encoding").orElse("").equals("gzip");
try (InputStream body = gzipped ? new GZIPInputStream(response.body()) : response.body()) {
    String json = new String(body.readAllBytes(), StandardCharsets.UTF_8);
}

Errors

Error responses use the same structured envelope as v2:

{
  "error": "Brief, human-readable error description",
  "detail": "Detailed explanation of what went wrong",
  "error_code": "MACHINE_READABLE_ERROR_CODE",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

retryable: true means the same request may succeed on retry, with backoff. retryable: false means you must change the request first. See Errors for the complete code reference. Two codes are worth knowing up front:

402 PAYMENT_REQUIRED: the organization is out of extraction credit, so the API rejected the run trigger.
400 TOPOLOGY_INVALID: a workflow create or update body failed graph validation. detail.violations lists each broken rule with the offending node ids.

v3 never returns 412 Precondition Failed. Where v2 used 412 to signal “results not ready yet”, v3 returns 200 with the run’s status field. See Get run.

Endpoints at a glance

Workflows

Method	Endpoint	Description
POST	`/v3/workflows/`	Create a workflow
GET	`/v3/workflows/`	List workflows
GET	`/v3/workflows/{workflow_id}/`	Get a workflow, with the full typed graph inline
GET	`/v3/workflows/{workflow_id}/versions/`	List a workflow’s versions. Read-only, for comparison and audit
PATCH	`/v3/workflows/{workflow_id}/`	Update a workflow
DELETE	`/v3/workflows/{workflow_id}/`	Delete a workflow

Upload

Method	Endpoint	Description
POST	`/v3/workflows/{workflow_id}/upload/`	Upload a document packet (no processing)
POST	`/v3/workflows/{workflow_id}/upload/run/`	Upload and run in one call
POST	`/v3/workflows/{workflow_id}/upload/from-url/`	Create a packet from URLs

Document packets

Method	Endpoint	Description
GET	`/v3/workflows/{workflow_id}/document-packets/`	List a workflow’s packets
GET	`/v3/document-packets/{document_packet_id}/`	Get a packet, with its files and `latest_run_id`
POST	`/v3/document-packets/{document_packet_id}/run/`	Run a packet. Returns a new `run_id`
DELETE	`/v3/document-packets/{document_packet_id}/`	Delete a packet

Runs

Method	Endpoint	Description
GET	`/v3/workflows/{workflow_id}/runs/`	List a workflow’s runs
GET	`/v3/runs/{run_id}/`	Get a run, with status and results inline

OpenAPI schema

The full OpenAPI specification is available at:

JSON: https://api.anyformat.ai/schema/?format=json
Swagger UI: https://api.anyformat.ai/docs/

Overview

Workflows

Upload

Document packets

Runs

Splits

Parse

Knowledge

Evals

SDKs and tools

API v2 (retired)

Base URL

Authentication

Resource model

Idempotency

Rate limits

Response headers

Compression

Errors

Endpoints at a glance

Workflows

Upload

Document packets

Runs

OpenAPI schema

​Base URL

​Authentication

​Resource model

​Pagination

​Idempotency

​Rate limits

​Response headers

​Compression

​Errors

​Endpoints at a glance

​Workflows

​Upload

​Document packets

​Runs

​OpenAPI schema

Base URL

Authentication

Resource model

Pagination

Idempotency

Rate limits

Response headers

Compression

Errors

Endpoints at a glance

Workflows

Upload

Document packets

Runs

OpenAPI schema