Get Started

# API Quickstart

> 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](/tutorials/parsing) and [Extract](/tutorials/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


```mermaid
flowchart LR
    A[Upload document] --> B[Create parsing]
    B --> C[Poll parsing]
    C --> D[Create extract]
    D --> E[Poll extract]
    E --> F[Use structured JSON]
```

## 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](/tutorials/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](/tutorials/schemas/create_schema).

### 3. Export convenient shell variables

Use environment variables to avoid repeating values in each command.

#### 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"
```

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


```http
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](/api/schema/documents/document_create) to upload the source file and get a reusable document ID.


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

Example response:


```json
{
  "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](/api/schema/parsings/parsing_create) to generate OCR output, markdown content, page-level information, and optional picture descriptions.


```bash
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:


```json
{
  "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](/api/schema/parsings/parsing_retrieve) until the parsing reaches a final state.


```bash
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:


```json
{
  "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](/tutorials/parsing) and [Extract](/tutorials/extract).

## Step 4: Create an extract from the parsing

Once the parsing is usable, call [Create extract](/api/schema/extracts/extract_create) with the parsing ID and your schema ID.


```bash
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:


```json
{
  "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](/api/schema/extracts/extract_retrieve) until the extract reaches a final state.


```bash
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:


```json
{
  "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:

| Resource | What it gives you |
|  --- | --- |
| Document | A reusable uploaded source file |
| Parsing | OCR, markdown, page-level processing data, and status tracking |
| Extract | Structured JSON generated from one schema |


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](/tutorials/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](/api/schema/extracts/extract_create) directly with:

* one document ID
* one public URL
* one uploaded file


See [Extract](/tutorials/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](/tutorials/parsing)
* [Extract](/tutorials/extract)
* [Parsing and extract status handling](/tutorials/parsing)
* [n8n parsing workflow](/tutorials/n8n/n8n-parsing)
* [AI agent integration guide](/tutorials/agent-guide)