Get Started

API Quickstart

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

Upload a document, create a parsing, and extract structured JSON with the Anesya API.

This guide walks through the fastest end-to-end Anesya workflow:

1. Upload a document
2. Parse it
3. Wait for processing to finish
4. Extract structured data with a schema
5. Retrieve the final JSON result

By the end of this quickstart, you will have a complete document-to-JSON pipeline running with the public API.

If you only need to understand supported payloads first, continue with Parsing and Extract.

What we are going to build

In this quickstart, we will process one business document such as an invoice, form, or contract page.

The goal is to:

• store the source document in Anesya
• generate OCR and markdown content with a parsing
• apply one schema to the parsing
• receive a structured JSON result that can be used in your product, workflow, or LLM pipeline

This is the most explicit and safest integration pattern because every step is visible and easy to debug.

How the flow works

Prerequisites

Before you start, make sure you have:

• an Anesya account
• one API key
• one schema ID
• one local document file such as invoice.pdf

1. Create an API key

Create your API key from the Anesya dashboard, then keep it available for the next commands.

If your docs deployment exposes it, you can also follow Create an API key.

2. Create or locate a schema

You need one schema ID for the extract step.

If you still need to define your schema, use Create schema.

3. Export convenient shell variables

Use environment variables to avoid repeating values in each command.

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"

All API calls below use the X-API-Key header:

X-API-Key: YOUR_API_KEY

The curl commands below use bash-style environment variables such as $ANESYA_API_KEY.

If you run them in PowerShell, replace:

• $ANESYA_API_KEY with $env:ANESYA_API_KEY
• $ANESYA_SCHEMA_ID with $env:ANESYA_SCHEMA_ID

Step 1: Upload a document

Use Create document to upload the source file and get a reusable document ID.

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" \
  -F 'metadata={"source":"api-quickstart"}'

Example response:

{
  "id": "300f339f-da71-4f9f-80f6-c25a63baae75",
  "filename": "invoice.pdf",
  "file_url": "/v0/documents/300f339f-da71-4f9f-80f6-c25a63baae75/download",
  "metadata": {
    "source": "api-quickstart"
  },
  "page_count": 3,
  "created_at": "2025-06-12T14:56:10.682461Z",
  "updated_at": "2025-06-12T14:56:10.682461Z"
}

Save the returned id. This is your document ID.

Step 2: Create a parsing

Use Create parsing to generate OCR output, markdown content, page-level information, and optional picture descriptions.

curl -X POST "https://api.anesya.app/v0/parsing" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "300f339f-da71-4f9f-80f6-c25a63baae75",
    "picture_description_enabled": false,
    "table_verification_enabled": false,
    "model": "PIGALLE",
    "metadata": {
      "source": "api-quickstart"
    }
  }'

Example response:

{
  "id": "d1b96998-f20e-4b6f-8fa5-78a70b1db9b2",
  "document": {
    "id": "300f339f-da71-4f9f-80f6-c25a63baae75",
    "filename": "invoice.pdf"
  },
  "picture_description_enabled": false,
  "table_verification_enabled": false,
  "model": "PIGALLE",
  "status": "IN_QUEUE",
  "created_at": "2025-06-12T14:57:00.000000Z",
  "updated_at": "2025-06-12T14:57:00.000000Z"
}

Save the returned parsing ID.

At this stage, the parsing is created but not finished yet.

Step 3: Poll the parsing until it is complete

Use Retrieve parsing until the parsing reaches a final state.

curl -X GET "https://api.anesya.app/v0/parsing/d1b96998-f20e-4b6f-8fa5-78a70b1db9b2" \
  -H "X-API-Key: $ANESYA_API_KEY"

The parsing is complete when status becomes one of:

• FINISHED
• PARTIAL_FINISHED
• ERROR

Example completed parsing response:

{
  "id": "d1b96998-f20e-4b6f-8fa5-78a70b1db9b2",
  "status": "FINISHED",
  "pages_total": 3,
  "pages_success": 3,
  "pages_failed": 0,
  "markdown_content": "# Invoice\n\nInvoice number: INV-2025-0042\n\nTotal: 1280.50 EUR",
  "ocr_content": {
    "pages": []
  },
  "pictures": [],
  "error": null
}

What to inspect in the parsing response

These fields are usually the most useful:

• status: current processing state
• markdown_content: extracted readable markdown
• ocr_content: structured OCR payload
• pages_total, pages_success, pages_failed: page-level outcome
• error: failure reason when the parsing fails

If the status is PARTIAL_FINISHED, the parsing can still be usable. Some pages failed, but successful pages are available.

For a full polling strategy, read Parsing and Extract.

Step 4: Create an extract from the parsing

Once the parsing is usable, call Create extract with the parsing ID and your schema ID.

curl -X POST "https://api.anesya.app/v0/extract" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"parsing\": \"d1b96998-f20e-4b6f-8fa5-78a70b1db9b2\",
    \"schema\": \"$ANESYA_SCHEMA_ID\"
  }"

Example response:

{
  "id": "e90f337f-4d7c-46d1-a2a7-13cf5d9d7cfe",
  "schema": {
    "id": "YOUR_SCHEMA_ID",
    "name": "Invoice schema",
    "description": "Schema used for extracting data from invoices.",
    "completion_mode": "CLASSIC"
  },
  "parsing": {
    "id": "d1b96998-f20e-4b6f-8fa5-78a70b1db9b2"
  },
  "result": null,
  "status": "IN_QUEUE",
  "error": null,
  "created_at": "2025-06-12T14:58:00.000000Z",
  "updated_at": "2025-06-12T14:58:00.000000Z"
}

Save the returned extract ID.

Step 5: Poll the extract until the JSON result is ready

Use Retrieve extract until the extract reaches a final state.

curl -X GET "https://api.anesya.app/v0/extract/e90f337f-4d7c-46d1-a2a7-13cf5d9d7cfe" \
  -H "X-API-Key: $ANESYA_API_KEY"

The extract is complete when status becomes one of:

• FINISHED
• ERROR

When the status is FINISHED, the structured output is available in result.

Example final response:

{
  "id": "e90f337f-4d7c-46d1-a2a7-13cf5d9d7cfe",
  "status": "FINISHED",
  "result": {
    "invoice_number": "INV-2025-0042",
    "invoice_date": "2025-06-01",
    "total_amount": 1280.5
  },
  "error": null
}

At this point, you can send the JSON result to your application, automation platform, or LLM workflow.

Understanding what you got back

After this quickstart, you have created three useful resources:

This separation is useful because it lets you:

• inspect the parsing before extraction
• reuse the same document later
• reuse the same parsing in downstream logic
• debug failures more easily than a single opaque request

Common variations

The flow above is the safest default, but you can simplify it depending on your use case.

Skip document upload

If your file is already available elsewhere, you can create a parsing directly from:

• one document ID
• one public URL
• one uploaded file
• a list of public URLs

See Parsing.

Skip the explicit parsing step

If you only need one final extract and do not need OCR or markdown separately, you can call Create extract directly with:

• one document ID
• one public URL
• one uploaded file

See Extract.

Troubleshooting

401 Unauthorized

Your API key is missing or invalid. Check the X-API-Key header and confirm that the key is active.

Parsing stays in IN_QUEUE or IN_PROGRESS

Keep polling. Parsing and extract jobs are asynchronous by design.

Parsing ends in PARTIAL_FINISHED

Inspect pages_failed and decide whether partial output is acceptable for your workflow.

Extract ends in ERROR

Check the error field, confirm that the parsing is already finished, and verify that the schema ID is valid.

What to read next

After this quickstart, the most useful next pages are:

• Parsing
• Extract
• Parsing and extract status handling
• n8n parsing workflow
• AI agent integration guide