Get Started

# Anesya API Reference for Coding Agents

> Complete, structured reference for coding agents integrating the Anesya document processing API.


This page is designed for AI coding agents and advanced automation systems that need one dense reference instead of navigating multiple pages.

It focuses on the public Anesya API currently documented in the public schema:

* Documents
* Parsings
* Extracts


## Product summary

Anesya processes business documents and exposes a simple resource-based workflow:

1. upload or reference a document
2. create a parsing
3. create an extract from a schema
4. poll until the final JSON result is available


### Core API facts

* **Base URL:** `https://api.anesya.app`
* **Auth header:** `X-API-Key: YOUR_API_KEY`
* **Primary integration surface:** REST API
* **Public entities:** `document`, `parsing`, `extract`
* **Input types:** document ID, public URL, pre-signed URL, multipart file, and URL list for parsing only


### Important agent note

The public API schema currently documents document, parsing, and extract endpoints.

It does **not** document a public schema-management endpoint in this spec, even though extract creation requires a schema ID.

An agent should therefore assume:

* a valid schema ID must already exist in the workspace
* schema creation or discovery may happen outside this public API flow


If the user asks how to create a schema, refer to [Create schema](/tutorials/schemas/create_schema).

## Authentication

Create an API key in the dashboard, then pass it on every request:


```http
X-API-Key: YOUR_API_KEY
```

### Environment variables

#### macOS / Linux


```bash
export ANESYA_API_KEY="YOUR_API_KEY"
export ANESYA_SCHEMA_ID="YOUR_SCHEMA_ID"
```

#### Windows PowerShell


```powershell
$env:ANESYA_API_KEY="YOUR_API_KEY"
$env:ANESYA_SCHEMA_ID="YOUR_SCHEMA_ID"
```

### Minimal authenticated request


```bash
curl -X GET "https://api.anesya.app/v0/documents" \
  -H "X-API-Key: $ANESYA_API_KEY"
```

## Resource model

| Resource | Purpose | How it is created | When to use it |
|  --- | --- | --- | --- |
| `Document` | Stored source file | `POST /v0/documents` | When the source file should be reusable |
| `Parsing` | OCR, markdown, page-level processing result | `POST /v0/parsing` | When you need parsing output or status visibility |
| `Extract` | Structured JSON generated from a schema | `POST /v0/extract` | When you need structured output |


### Relationship between resources

* A `parsing` is created from a `document`, a public URL, a pre-signed URL, a multipart file, or a list of URLs
* An `extract` is created either:
  * from an existing `parsing`
  * or directly from a `document`, in which case a new parsing is created first


## Which endpoint should the agent use?

| Goal | Endpoint | Method | Input shape | Notes |
|  --- | --- | --- | --- | --- |
| Upload and store a reusable file | `/v0/documents` | `POST` | multipart file | Returns a document ID |
| Browse stored documents | `/v0/documents` | `GET` | query params | Paginated response |
| Retrieve one document | `/v0/documents/{id}` | `GET` | path ID | Returns one document |
| Download one document | `/v0/documents/{id}/download` | `GET` | path ID | Redirects to file URL |
| Get OCR, markdown, pictures, and page-level processing data | `/v0/parsing` | `POST` | document ID, URL, file, or URL list | URL list returns multiple parsings |
| Browse parsings | `/v0/parsing` | `GET` | query params | Paginated response |
| Retrieve one parsing | `/v0/parsing/{id}` | `GET` | path ID | Use for polling and inspection |
| Generate structured JSON from a parsing or document | `/v0/extract` | `POST` | parsing ID or document + schema ID | Requires `schema` |
| Retrieve one extract | `/v0/extract/{id}` | `GET` | path ID | Use for polling and final result retrieval |


## Canonical workflow for agents

The safest default workflow is:

1. upload the file with `/v0/documents` if a reusable document reference is useful
2. create a parsing with `/v0/parsing`
3. poll `/v0/parsing/{id}` until the parsing is final
4. create an extract with `/v0/extract`
5. poll `/v0/extract/{id}` until the extract is final
6. consume `extract.result`


This is the preferred workflow when:

* the user needs OCR or markdown separately
* the user needs observability and easy debugging
* the input shape is complex
* the agent should avoid hidden intermediate work


## Documents endpoint reference

### `GET /v0/documents`

List stored documents.

#### Query parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `page` | integer | Page number |
| `size` | integer | Page size |
| `search` | string | Search in filename and metadata values |
| `created_at_after` | date-time | Filter lower bound |
| `created_at_before` | date-time | Filter upper bound |


#### Response shape


```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "filename": "invoice.pdf",
      "file_url": "/v0/documents/uuid/download",
      "metadata": {"source": "api"},
      "page_count": 3,
      "created_at": "2025-06-12T14:56:10.682461Z",
      "updated_at": "2025-06-12T14:56:10.682461Z"
    }
  ]
}
```

### `POST /v0/documents`

Upload one document.

#### Multipart fields

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `file` | binary | yes | Source document file |
| `filename` | string | no | Optional filename override |
| `metadata` | object | no | Optional metadata object |


#### Example


```bash
curl -X POST "https://api.anesya.app/v0/documents" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -F "file=@invoice.pdf;type=application/pdf" \
  -F "filename=invoice.pdf"
```

### `GET /v0/documents/{id}`

Retrieve one document by ID.

### `GET /v0/documents/{id}/download`

Get the download URL for the stored file.

Important behavior:

* response status is `302`
* agent should follow redirects if it needs the actual file


## Parsing endpoint reference

### `POST /v0/parsing`

Create one or more parsings.

### Supported `document` shapes

| Shape | Example | Allowed |
|  --- | --- | --- |
| existing document ID | `"300f339f-da71-4f9f-80f6-c25a63baae75"` | yes |
| public or pre-signed URL | `"https://example.com/invoice.pdf"` | yes |
| multipart file | binary upload | yes |
| list of public or pre-signed URLs | `["https://a.pdf", "https://b.pdf"]` | yes |


### Parameters

| Field | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `document` | union | yes | - | Document ID, URL, binary file, or URL list |
| `picture_description_enabled` | boolean | no | `false` | Enable image descriptions |
| `table_verification_enabled` | boolean | no | `false` | Stronger table verification |
| `model` | enum | no | `PIGALLE` | `PIGALLE` or `PIGALLE_LITE` |
| `metadata` | object | no | `null` | Optional metadata |


### Response handling rule

`POST /v0/parsing` is the most important shape-switching endpoint.

The response can be:

* **one parsing object** when the input is a document ID, one URL, or one file
* **an array of parsing objects** when the input is a list of URLs


An agent must not assume this endpoint always returns one object.

### Canonical JSON example


```json
{
  "document": "YOUR_DOCUMENT_ID",
  "picture_description_enabled": false,
  "table_verification_enabled": false,
  "model": "PIGALLE",
  "metadata": {
    "source": "agent"
  }
}
```

### Canonical URL-list example


```json
{
  "document": [
    "https://example.com/doc-1.pdf",
    "https://example.com/doc-2.pdf"
  ],
  "model": "PIGALLE_LITE"
}
```

### `GET /v0/parsing`

List parsings.

#### Query parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `page` | integer | Page number |
| `size` | integer | Page size |
| `search` | string | Search in filename and metadata values |
| `status` | string | One of `IN_QUEUE`, `IN_PROGRESS`, `FINISHED`, `PARTIAL_FINISHED`, `ERROR` |
| `created_at_after` | date-time | Filter lower bound |
| `created_at_before` | date-time | Filter upper bound |


### `GET /v0/parsing/{id}`

Retrieve one parsing.

#### Important response fields

| Field | Meaning |
|  --- | --- |
| `status` | Current parsing state |
| `markdown_content` | Extracted markdown text |
| `ocr_content` | OCR payload |
| `pictures` | Image-level entries |
| `pages_total` | Total pages |
| `pages_success` | Successfully processed pages |
| `pages_failed` | Failed pages |
| `error` | Error message if parsing failed |


### Parsing status model

| Status | Meaning | Agent action |
|  --- | --- | --- |
| `IN_QUEUE` | Waiting to start | keep polling |
| `IN_PROGRESS` | Running | keep polling |
| `FINISHED` | Completed successfully | safe to continue |
| `PARTIAL_FINISHED` | Completed with partial page failure | usually safe to continue |
| `ERROR` | Failed | stop and inspect `error` |


## Extract endpoint reference

### `POST /v0/extract`

Create one extract from either:

* an existing parsing
* or one document input plus a schema


### Required rules

The request must include:

* `schema`


The request must include exactly one of:

* `document`
* `parsing`


When `document` is used, a new parsing is created first.

### Supported `document` shapes on extract

| Shape | Allowed |
|  --- | --- |
| existing document ID | yes |
| public or pre-signed URL | yes |
| multipart file | yes |
| URL list | no documented support |


### Parameters

| Field | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `document` | union | conditional | - | Existing document ID, URL, or multipart file |
| `parsing` | string UUID | conditional | - | Existing parsing ID |
| `schema` | string UUID | yes | - | Existing schema ID |
| `picture_description_enabled` | boolean | no | `false` | Applied only when a new parsing is created from `document` |
| `table_verification_enabled` | boolean | no | `false` | Applied only when a new parsing is created from `document` |
| `model` | enum | no | `PIGALLE` | Applied only when a new parsing is created from `document` |
| `metadata` | object | no | `null` | Applied only when a new parsing is created from `document` |


### Canonical extract-from-parsing payload


```json
{
  "parsing": "YOUR_PARSING_ID",
  "schema": "YOUR_SCHEMA_ID"
}
```

### Canonical direct-extract payload


```json
{
  "document": "YOUR_DOCUMENT_ID",
  "schema": "YOUR_SCHEMA_ID",
  "model": "PIGALLE"
}
```

### Response handling rule

The extract response is one extract object.

The `result` field can be:

* `null` while processing
* an object
* an array of objects


This is because the public schema models `result` as a generic JSON payload.

An agent must therefore treat `extract.result` as **arbitrary JSON**, not as a fixed object shape.

### `GET /v0/extract/{id}`

Retrieve one extract.

#### Important response fields

| Field | Meaning |
|  --- | --- |
| `status` | Current extract state |
| `result` | Final structured JSON when finished |
| `error` | Error message if extraction failed |
| `schema` | Schema metadata |
| `parsing` | Related parsing object |


### Extract status model

| Status | Meaning | Agent action |
|  --- | --- | --- |
| `IN_QUEUE` | Waiting to start | keep polling |
| `IN_PROGRESS` | Running | keep polling |
| `FINISHED` | Completed successfully | consume `result` |
| `ERROR` | Failed | stop and inspect `error` |


## Polling rules for agents

After any successful `POST` to `/v0/parsing` or `/v0/extract`:

1. store the returned resource ID
2. wait a short interval
3. call the corresponding retrieve endpoint
4. inspect `status`
5. stop only when the resource is in a final state


### Recommended final states

#### Parsing

* `FINISHED`
* `PARTIAL_FINISHED`
* `ERROR`


#### Extract

* `FINISHED`
* `ERROR`


### Canonical pseudo-code


```text
repeat
  resource = GET by ID
  status = resource.status

  if status is final:
    stop

  wait 2 to 5 seconds
end
```

## Deterministic agent decision rules

Use these rules in order:

1. If the task requires OCR output, markdown content, pictures, or page-level processing visibility, use `/v0/parsing`.
2. If a completed parsing already exists and the task requires structured data, use `/v0/extract` with `parsing`.
3. If the task only needs one final structured result from one raw document, `/v0/extract` with `document` is acceptable.
4. If the input is a list of URLs, use `/v0/parsing` first, then create one extract per parsing.
5. If reuse matters, create a stored `document` first with `/v0/documents`.


### Safe default when the request is ambiguous

Prefer:

1. document upload
2. parsing creation
3. parsing polling
4. extract creation
5. extract polling


This minimizes hidden behavior and improves debuggability.

## Canonical cURL workflow

### 1. Upload a file


```bash
curl -X POST "https://api.anesya.app/v0/documents" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -F "file=@invoice.pdf;type=application/pdf" \
  -F "filename=invoice.pdf"
```

### 2. Create a parsing


```bash
curl -X POST "https://api.anesya.app/v0/parsing" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "YOUR_DOCUMENT_ID",
    "model": "PIGALLE"
  }'
```

### 3. Poll the parsing


```bash
curl -X GET "https://api.anesya.app/v0/parsing/YOUR_PARSING_ID" \
  -H "X-API-Key: $ANESYA_API_KEY"
```

### 4. Create an extract


```bash
curl -X POST "https://api.anesya.app/v0/extract" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parsing": "YOUR_PARSING_ID",
    "schema": "YOUR_SCHEMA_ID"
  }'
```

### 5. Poll the extract


```bash
curl -X GET "https://api.anesya.app/v0/extract/YOUR_EXTRACT_ID" \
  -H "X-API-Key: $ANESYA_API_KEY"
```

## Common agent failure modes

An agent should explicitly avoid these mistakes:

* sending both `document` and `parsing` in the extract payload
* omitting `schema` when creating an extract
* treating parsing URL-list responses as one object
* assuming a `POST` response means processing is complete
* treating `PARTIAL_FINISHED` as a hard failure without checking whether partial output is acceptable
* trying to send a list of URLs directly to the extract endpoint
* assuming `extract.result` is always an object rather than generic JSON


## Error model

The public schema currently documents these common HTTP outcomes:

| HTTP status | Meaning |
|  --- | --- |
| `200` | Resource retrieved successfully |
| `201` | Resource created and processing started |
| `302` | Document download redirects to the file URL |
| `400` | Missing or invalid request fields |
| `401` | Missing or invalid API key |
| `404` | Resource not found |


### Common error shapes

#### Authentication error


```json
{
  "detail": "Invalid API key"
}
```

#### Not found


```json
{
  "detail": "Parsing not found."
}
```

#### Validation error


```json
{
  "detail": "Missing or invalid fields"
}
```

Validation errors may also be keyed by field name.

## Recommended companion pages

* [API quickstart](/tutorials/quickstart)
* [Parsing guide](/tutorials/parsing)
* [Extract guide](/tutorials/extract)
* [Quickstart polling flow](/tutorials/quickstart)
* [n8n parsing workflow](/tutorials/n8n/n8n-parsing)
* [Create schema](/tutorials/schemas/create_schema)
* [API reference](/api/schema)