> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions.

# FAQ

<AccordionGroup>
  <Accordion title="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](/docs/concepts/caching).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/docs/concepts/formats) and [Heavy files and limits](/docs/api/heavy-and-limits).
  </Accordion>

  <Accordion title="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](/docs/concepts/compression).
  </Accordion>

  <Accordion title="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](/docs/concepts/caching).
  </Accordion>

  <Accordion title="What mode do I use?" />

  <Accordion title="What if my PDF is scanned (no selectable text)?" />

  <Accordion title="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](/docs/api/heavy-and-limits).
  </Accordion>

  <Accordion title="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](/docs/api/jobs).
  </Accordion>

  <Accordion title="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](/docs/api/pdf-index).
  </Accordion>

  <Accordion title="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](/docs/concepts/self-hosted-storage).
  </Accordion>

  <Accordion title="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](/docs/security).
  </Accordion>

  <Accordion title="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](/docs/api/convert-from-url).
  </Accordion>
</AccordionGroup>