Get Started
Upload, store, retrieve, and download reusable source documents.
Documents is the Anesya resource for storing source files in your workspace before downstream processing.
Use it when you want a stable document ID that can later be reused by:
- parsing
- extract
- list and search workflows
- operational or audit flows around uploaded files
If you do not need a reusable stored file, you can sometimes skip this step and send a file or URL directly to parsing or extract.
Documents is the right entry point when you want to:
- upload one local file to Anesya
- keep a reusable file reference in the workspace
- list previously uploaded files
- search documents by filename or metadata
- download the stored source file later
- trim a PDF before parsing or extraction
The common workflow is:
The most common document workflow has three steps:
- upload one file
- keep the returned document ID
- reuse that ID in parsing or extract
Use Create document to store a new 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" \
-F 'metadata={"source":"api"}'Example response:
{
"id": "300f339f-da71-4f9f-80f6-c25a63baae75",
"filename": "invoice.pdf",
"file_url": "/v0/documents/300f339f-da71-4f9f-80f6-c25a63baae75/download",
"metadata": {
"source": "api"
},
"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 the document ID you can reuse later.
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"
}'curl -X POST "https://api.anesya.app/v0/extract" \
-H "X-API-Key: $ANESYA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document": "YOUR_DOCUMENT_ID",
"schema": "YOUR_SCHEMA_ID"
}'The document resource returned by create, retrieve, and list contains:
{
"id": "300f339f-da71-4f9f-80f6-c25a63baae75",
"filename": "invoice.pdf",
"file_url": "/v0/documents/300f339f-da71-4f9f-80f6-c25a63baae75/download",
"metadata": {
"source": "api"
},
"page_count": 3,
"created_at": "2025-06-12T14:56:10.682461Z",
"updated_at": "2025-06-12T14:56:10.682461Z"
}| Field | What it contains |
|---|---|
id | Stable document identifier |
filename | Stored file name |
file_url | Relative download endpoint for this file |
metadata | Custom metadata object |
page_count | Number of pages in the stored document |
created_at | Creation timestamp |
updated_at | Last update timestamp |
The documents resource exposes four public actions.
Upload one new file and create a document resource.
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | yes | Source document file |
filename | string | no | Optional filename override |
metadata | object | no | Optional metadata object |
| Parameter | Type | Description |
|---|---|---|
pdf_page_start | integer | Optional first PDF page to keep |
pdf_page_end | integer | Optional last PDF page to keep |
This PDF trimming happens at upload time.
It is useful when:
- the original PDF is larger than the subset you need
- you want to reduce downstream parsing work
- only a known page range matters
List documents in the workspace.
| 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 |
Retrieve one document by its UUID.
Get the download URL for the stored file.
Important behavior:
- the documented response is
302 - clients that want the actual file should follow the redirect
Documents has three main response shapes.
Both POST /v0/documents and GET /v0/documents/{id} return one document object.
GET /v0/documents returns a paginated resource:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "300f339f-da71-4f9f-80f6-c25a63baae75",
"filename": "invoice.pdf"
}
]
}GET /v0/documents/{id}/download does not return the normal document object.
Instead, it redirects to the underlying file URL.
Document listing supports lightweight search and date filtering.
Use the search query parameter to search in:
- the document filename
- metadata values
Example:
curl -X GET "https://api.anesya.app/v0/documents?search=invoice" \
-H "X-API-Key: $ANESYA_API_KEY"Use:
created_at_aftercreated_at_before
Example:
curl -X GET "https://api.anesya.app/v0/documents?created_at_after=2026-04-01T00:00:00Z&created_at_before=2026-04-30T23:59:59Z" \
-H "X-API-Key: $ANESYA_API_KEY"Use documents first when:
- the file should be reused later
- you want a stable internal document ID
- the workflow may involve several downstream steps
- the source file should be discoverable in list views
- you want to trim a PDF once and reuse the trimmed version
Skip documents and go directly to parsing or extract when:
- you only need one one-off processing call
- the file is already available as a public or pre-signed URL
- you do not need a stored document lifecycle
If the same file may be parsed again, extracted again, or audited later, upload it first and keep the document ID.
Good metadata makes list and search workflows much easier.
Typical metadata examples:
- source system
- customer ID
- import batch identifier
- internal reference number
If you only need a subset of pages, use pdf_page_start and pdf_page_end at upload time.
This avoids carrying an oversized document through the rest of the pipeline.
Once a document is uploaded, reuse the UUID rather than re-uploading the same file repeatedly.
If you call the download endpoint programmatically, make sure your client follows 302 redirects or handles the redirected URL explicitly.
If the file is meant to be reused, upload it once and keep the document ID.
If search results seem broader than expected, remember that metadata values are part of the search surface.
The documented behavior is a redirect, not a standard document object.
If you trim pages during upload, the stored document itself reflects that subset.
That is usually desirable, but it should be intentional.
Your API key is missing or invalid. Check the X-API-Key header.
The document ID does not exist, is not accessible in the current workspace context, or the file is missing.
Check that:
- the
filefield is present - the multipart request is correctly formed
- the PDF trim parameters are valid if you used them
Your client may not be following redirects automatically.
Handle the 302 response correctly.