Get Started

Anesya API Reference for Coding Agents

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

Authentication

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

X-API-Key: YOUR_API_KEY

Environment variables

macOS / Linux

export ANESYA_API_KEY="YOUR_API_KEY"
export ANESYA_SCHEMA_ID="YOUR_SCHEMA_ID"

Windows PowerShell

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

Minimal authenticated request

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

Resource model

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?

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

Response shape

{
  "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

Example

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

Parameters

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

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

Canonical URL-list example

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

GET /v0/parsing

List parsings.

Query parameters

GET /v0/parsing/{id}

Retrieve one parsing.

Important response fields

Parsing status model

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

Parameters

Canonical extract-from-parsing payload

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

Canonical direct-extract payload

{
  "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

Extract status model

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

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

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

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

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

4. Create an extract

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

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:

Common error shapes

Authentication error

{
  "detail": "Invalid API key"
}

Not found

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

Validation error

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

Validation errors may also be keyed by field name.

Recommended companion pages

• API quickstart
• Parsing guide
• Extract guide
• Quickstart polling flow
• n8n parsing workflow
• Create schema
• API reference