FAQ

Does the API cache my documents?

No. The API converts and returns Markdown; it does not persist your documents or the result after responding, except for the temporary result of a queued 202 job, which expires after about 1 hour. If you want caching on your side, use your own storage along with the ETag header. See Cache and ETag.

Why Markdown and not plain text?

Agents read structured Markdown better than unordered text: headings (#, ##) mark hierarchy, tables remain in recognizable syntax, and lists are not confused with single paragraphs. By cleaning noise such as repeated headers, footers, and redundant line breaks, the resulting Markdown also usually uses far fewer tokens than raw extracted text.

Can I send a ZIP?

Yes. It must contain a supported format and respect the limits on number of files (MAX_ZIP_FILES) and size per member (MAX_ZIP_MEMBER_BYTES). The first supported document found inside the ZIP is processed. See Formats and Heavy files and limits.

How do I speed up large uploads?

Use POST /convert/raw with content-encoding: gzip or zstd to reduce bytes traveling over the network. Remember that /convert/raw has a separate body limit (RAW_UPLOAD_MAX_BYTES, 12 MB by default, measured after decompression). For larger documents, use /convert/from-url instead of uploading the binary. See Compression.

How do I avoid reconverting the same document?

Save the ETag you receive in the response and resend the same request with the If-None-Match header. If the document and parameters did not change, you receive 304 without paying the conversion cost again. See Cache.

What mode do I use?

What if my PDF is scanned (no selectable text)?

What is the maximum document size?

500 MB by default (MAX_INPUT_BYTES/FETCH_MAX_BYTES), capped at 5000 PDF pages (MAX_PDF_PAGES). If you upload the direct binary with /convert/raw, the real limit is much lower (12 MB, RAW_UPLOAD_MAX_BYTES) because that endpoint is not designed for large files. For large documents use /convert/from-url. See Heavy files and limits.

What if all the backends are busy?

Any conversion endpoint can respond 202 with a job_id instead of blocking your request. Poll GET /jobs/{id} every Retry-After seconds (5s by default) until the status is completed or failed. This is automatic: you do not need to enable it, and under normal conditions you will still receive 200 directly. See Jobs.

Do I need to index a large PDF before converting it?

Only if you are interested in part of the document, not all of it. POST /pdf/index returns a compact map (sections, pages, estimated font size) for a fraction of the cost of converting the entire document. With that map you can then request only the relevant page range via pages= in /convert/from-url. For small documents (less than 10 pages), skip the index and convert directly. See POST /pdf/index.

How do I send documents already hosted in my own storage (self-hosted, not cloud)?

/convert/from-url accepts any signed https URL, including self-hosted S3-compatible storage such as MinIO, Garage, or SeaweedFS. Generate a short-lived signed URL from your storage. See Self-hosted S3.

Does the API modify or save my documents anywhere?

It does not save them persistently. It converts in memory or temporary storage and returns the result. The only brief persistence is the result of a 202 job, which expires after about 1 hour, or your own output_url, where the API uploads Markdown to your storage. See Security.

How do I prevent uploading a large document from consuming time of my serverless function (Lambda, Cloud Functions, etc.)?

Use output_url in /convert/from-url: instead of returning the full Markdown in the response body, the API uploads it directly to a pre-signed PUT URL in your storage and returns a small JSON reference. This reduces backend execution time and output bandwidth. See POST /convert/from-url.

​FAQ