> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> REST API overview — base URL, authentication, rate limits, response envelope, and error model.

anyformat exposes a REST API that lets you programmatically create [workflows](/concepts/workflows), process documents, and retrieve [results](/concepts/runs-and-results). This page is the orientation guide — for a step-by-step walkthrough, see the [quickstart](/guides/quickstart).

For terminology (Workflow, Field, Run, etc.) start at [Concepts](/concepts/workflows). For complete worked examples (invoices, resumes, contracts, …) see [Recipes](/guides/recipes/index).

***

## Base URL

```
https://api.anyformat.ai/
```

All v2 endpoints use the `/v2/` prefix — for example, `https://api.anyformat.ai/v2/workflows/`. When a new major version ships, `/v2/` will continue to serve traffic for a bounded deprecation window — see [Versioning & deprecation](#versioning--deprecation) below to wire your integration for alerting.

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 (except `/docs/` and `/schema/`) require an API key, passed as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.anyformat.ai/v2/workflows/
```

See [Authentication](/api-reference/authentication) for how to obtain and manage API keys.

***

## Rate limits

The API uses two-tier rate limiting. File submission endpoints have a stricter limit; all other endpoints share a higher general limit.

| Tier           | Endpoints                                                                                           | Limit            |
| -------------- | --------------------------------------------------------------------------------------------------- | ---------------- |
| **Submission** | `POST /v2/workflows/{id}/run/`, `POST /v2/workflows/{id}/upload/`, `POST /v2/workflows/{id}/files/` | 60 requests/min  |
| **General**    | All other authenticated endpoints                                                                   | 600 requests/min |

Each tier has an independent counter — extraction endpoints don't consume your general quota, and vice versa.

If you exceed a limit, the API responds with `429 Too Many Requests`. Wait for the number of seconds in the `Retry-After` header before retrying.

All successful responses include rate-limit headers for the tier that applies:

| Header                  | Description                          |
| ----------------------- | ------------------------------------ |
| `x-ratelimit-limit`     | Maximum requests allowed per window  |
| `x-ratelimit-remaining` | Requests remaining in current window |
| `x-ratelimit-reset`     | Seconds until the rate limit resets  |

<Note>
  The `Retry-After` header appears only in 429 responses, not in every response.
</Note>

***

## Endpoints at a glance

The API is organized around three resource groups.

### Workflows

| Method | Endpoint                     | Description                                                      |
| ------ | ---------------------------- | ---------------------------------------------------------------- |
| POST   | `/v2/workflows/`             | [Create a workflow](/api-reference/workflows/create)             |
| GET    | `/v2/workflows/`             | [List workflows](/api-reference/workflows/list)                  |
| GET    | `/v2/workflows/{id}/`        | [Get a workflow](/api-reference/workflows/get)                   |
| DELETE | `/v2/workflows/{id}/`        | [Delete a workflow](/api-reference/workflows/delete)             |
| POST   | `/v2/workflows/{id}/run/`    | [Run a workflow on a file](/api-reference/workflows/run)         |
| POST   | `/v2/workflows/{id}/upload/` | [Upload a file (no processing)](/api-reference/workflows/upload) |
| GET    | `/v2/workflows/{id}/runs/`   | [List workflow runs](/api-reference/workflows/runs)              |

### Files

| Method | Endpoint                                          | Description                                  |
| ------ | ------------------------------------------------- | -------------------------------------------- |
| POST   | `/v2/workflows/{workflow_id}/files/`              | [Upload a file](/api-reference/files/create) |
| GET    | `/v2/workflows/{workflow_id}/files/`              | [List files](/api-reference/files/list)      |
| DELETE | `/v2/files/{id}/`                                 | [Delete a file](/api-reference/files/delete) |
| GET    | `/v2/workflows/{workflow_id}/files/{id}/results/` | [Get results](/api-reference/files/results)  |

### Webhooks

| Method | Endpoint             | Description                                        |
| ------ | -------------------- | -------------------------------------------------- |
| POST   | `/v2/webhooks/`      | [Create a webhook](/api-reference/webhooks/create) |
| GET    | `/v2/webhooks/`      | [List webhooks](/api-reference/webhooks/list)      |
| DELETE | `/v2/webhooks/{id}/` | [Delete a webhook](/api-reference/webhooks/delete) |

See [Webhooks overview](/api-reference/webhooks/overview) for setup, signing, and delivery semantics.

***

## Response format

Successful responses are JSON. The detailed envelope (including `as_lists=true` for tabular shapes) is documented in [Response formats](/api-reference/response-formats).

Error responses follow a consistent structured shape:

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

See [Errors](/api-reference/errors) for the complete error code reference and retry patterns.

***

## Versioning & deprecation

The API is versioned in the URL path. The current stable major is `/v2/`. When a new major (e.g. `/v3/`) is introduced, the previous one continues to serve traffic through an announced deprecation window before it is shut down.

<Warning>
  `/v2/` is deprecated and sunsets on **October 3, 2026**. See the [v2 → v3 migration guide](/api-reference/v2-migration) for the endpoint-by-endpoint mapping.
</Warning>

### Response headers

Every response carries a version identifier, plus deprecation signals whenever the version you called is on the retirement path.

| Header          | When emitted                           | Value                                                                                                       |
| --------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `X-API-Version` | Every `/v2/` response                  | Current major version (e.g. `2.0.0`)                                                                        |
| `Deprecation`   | Only while a version is deprecated     | HTTP-date the deprecation was announced ([RFC 8594](https://datatracker.ietf.org/doc/html/rfc8594))         |
| `Sunset`        | Only while a version is deprecated     | HTTP-date after which the version stops serving traffic                                                     |
| `Link`          | Only when a per-route successor exists | `<https://api.anyformat.ai/vN/...>; rel="successor-version"` — the equivalent endpoint on the newer version |

Example — a call to a deprecated endpoint:

```http theme={null}
HTTP/1.1 200 OK
X-API-Version: 2.0.0
Deprecation: Fri, 03 Jul 2026 00:00:00 GMT
Sunset: Sat, 03 Oct 2026 00:00:00 GMT
Link: </v3/workflows/abc/>; rel="successor-version"
Content-Type: application/json
```

The `Deprecation` and `Sunset` headers are absent while a version is not deprecated — so their presence alone is a reliable signal that migration work is due.

### Don't get surprised — alert on `Sunset`

Deprecation windows are typically **three months** between the `Deprecation` announcement and the `Sunset` cutoff. Rather than tracking release notes by hand, we strongly recommend wiring your integration to detect these headers automatically. A minimal setup:

* **In your HTTP client middleware**, check every response for a `Sunset` header. If present, emit a warning to your logs or monitoring system that includes the endpoint path and the sunset date.
* **In your metrics / observability stack**, add a counter or gauge indexed by `X-API-Version`, `Deprecation`, and `Sunset`. A dashboard panel or alert firing on "any response has `Sunset`" gives on-call visibility without human polling.
* **Escalate as the sunset approaches**: for example, log-level warning at first sight, page on-call one month before `Sunset`, hard-fail your CI a week before if you still have live traffic on the deprecated version.

Example — a five-line Python wrapper around `requests` that surfaces the signal:

```python theme={null}
import logging
import requests

def call(method: str, url: str, **kw) -> requests.Response:
    response = requests.request(method, url, **kw)
    if sunset := response.headers.get("Sunset"):
        logging.warning(
            "anyformat API deprecation: %s %s sunsets %s (successor: %s)",
            method, url, sunset, response.headers.get("Link", "n/a"),
        )
    return response
```

Equivalent hooks exist in `httpx` (event hooks), `axios` (interceptors), `fetch` (a wrapping function), and every other mainstream HTTP client.

If you can only pick one thing: **alert on the `Sunset` header**. Everything else — endpoint, announcement date, successor URL — is derivable from the same response.

***

## SDKs

Official client libraries with a fluent builder over the typed-graph API:

* [TypeScript SDK](/api-reference/sdks/typescript) — `npm install @anyformat/sdk`
* [Python SDK](/api-reference/sdks/python) — `pip install anyformat`
* [SDKs overview](/api-reference/sdks/overview) — both client libraries and the Claude Code skill

***

## OpenAPI schema

The full OpenAPI specification is available at:

* **JSON**: [https://api.anyformat.ai/schema/?format=json](https://api.anyformat.ai/schema/?format=json)
* **Swagger UI**: [https://api.anyformat.ai/docs/](https://api.anyformat.ai/docs/)