Frequently Asked Questions

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

Use documents when you want a reusable stored file and a stable document ID.

Use parsing when you need to inspect the document itself through OCR output, markdown, pictures, or page-level status details.

Use extract when you already know the business structure you want and only need the final JSON result for one schema.

A common production flow is:

1. upload a document
2. create a parsing
3. inspect the parsing if needed
4. create an extract from that parsing

See Documents, Parsing, and Extract.

Yes. Both parsing and extract support a public or pre-signed URL as input.

This is useful when your files already live in object storage or are generated by another system.

If the same file will be reused later, uploading it once through /v0/documents is usually cleaner because you then work with a stable internal document ID instead of an external URL that may expire.

Parsing documents supports a documented URL-list input. If you send a list of public or pre-signed URLs to POST /v0/parsing, the API returns an array of parsing resources.

Extract does not document the same URL-list behavior. If you need one extract per file, the safe workflow is:

1. create multiple parsings from the URL list
2. poll each parsing
3. create one extract per parsing

See Parsing.

Because the endpoint has two create behaviors:

• one parsing object for one document input
• an array of parsing objects when document is a list of URLs

This is a common integration mistake in no-code tools and coding agents. Your client should branch on the input format instead of assuming a single fixed response shape.

The two main levers are:

• reuse stored documents and existing parsings when possible
• trim PDFs early with pdf_page_start and pdf_page_end during document upload

If you only need a few pages from a long PDF, trimming at upload time is often the simplest way to reduce downstream work for both parsing and extract.

See Documents and Credit usage.

Parsing and extract are asynchronous workflows. Creating the resource means the job has been accepted, not that the final output is ready.

After POST /v0/parsing or POST /v0/extract, poll the resource until it reaches a final status.

See API quickstart.

PARTIAL_FINISHED is a parsing status meaning the job completed but one or more pages failed.

It is not the same as FINISHED, and it is not a total failure either. Many workflows can still continue if the failed pages are not business-critical.

Before deciding what to do, inspect:

• pages_total
• pages_success
• pages_failed
• error

For parsing, stop when status is:

• FINISHED
• PARTIAL_FINISHED
• ERROR

For extract, stop when status is:

• FINISHED
• ERROR

Anything else means the resource is still progressing.

The most common reason is that the parsing is not ready yet.

If you create an extract from a parsing, wait for the parsing to reach a usable final state first. In practice, that means FINISHED or, when your workflow tolerates it, PARTIAL_FINISHED.

See Extract.

Start with the parsing, not the schema output.

Extract depends on parsing. If the document content is missing, badly OCRed, or only partially processed, the extract result will also be weak.

The safest debugging sequence is:

1. retrieve the parsing
2. inspect markdown_content, ocr_content, and page counters
3. confirm the needed information is actually present
4. only then review the schema and extract logic

See Parsing and Extract.

Enable picture_description_enabled when image understanding matters to the workflow.

Enable table_verification_enabled when table accuracy matters more than keeping the request as simple as possible.

If your use case does not depend on those features, leave them disabled and keep the request minimal.

Use the query parameters on document creation:

• pdf_page_start
• pdf_page_end

This trims the PDF at upload time and stores only the selected page range as the document resource you reuse later.

See Documents.

GET /v0/documents/{id}/download is documented as a 302 redirect.

That means your HTTP client must follow the redirect, or you must manually handle the returned location, to access the underlying file.

Credits are calculated per page, according to the endpoint being used.

The documented base rates are:

• parsing standard: 2 credits per page
• extract: 3 credits per page
• split: 2 credits per page
• classify: 1 credit per page

See Credit usage.

Send your API key in the X-API-Key header:

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

If the header is missing or invalid, the API returns 401 Unauthorized.

Start with these three checks:

1. the HTTP status code
2. the error field on the resource when available
3. the input type you sent, especially URL vs document ID vs parsing ID

See Error codes.

For API issues or product questions, contact support@anesya.app.