# Parsing PDF, DOCX, XLSX and EPUB for agents

URL: https://grist.tools/guides/document-parsing-api (updated 2026-09-28)

An agent extracts text, Markdown or JSON by sending a public document URL to the endpoint for its format: PDF, DOCX, PPTX, XLSX, EPUB or CSV. Use image OCR for scans, screenshots and photos, then inspect extraction limits and warnings before passing the result into the next stage.

## Start with the output your agent needs

Call `POST https://grist.tools/v1/<name>` with a JSON body and `content-type: application/json`. Most document endpoints fetch the public URL in `url`; fetch the free input schema at `GET /v1/<name>/schema` before constructing the request. `/openapi.json` also publishes the schemas. No account or API key is required.

Choose text for a reading task, Markdown when the supported conversion structure is useful, and JSON rows for tabular work. The table below covers the documents family, including extraction, PDF utilities and output rendering. Use its endpoint documentation links for the full input contract and its generated limits when planning each call.

## PDF text layers and image OCR are separate paths

Use `pdf-to-text` to extract the PDF text layer page by page in reading order. Choose `pdf-to-markdown` for Markdown with headings inferred from font size. That inference is best effort and does not reproduce the layout exactly. Both accept `max_pages` for leading pages, and neither performs OCR. The example below demonstrates `pdf-to-markdown` and its returned Markdown.

Both PDF extractors operate without fetching external CMap or standard-font data. Self-contained character mappings can yield text, including CJK, but a document needing unavailable predefined CMaps can return empty or partial text without an error. Embedded `ToUnicode` alone does not guarantee extraction when the encoding still needs an external CMap. Missing standard-font data does not necessarily prevent extraction.

For an image, choose `ocr-image-to-text`. It accepts PNG, JPEG, TIFF, WebP and GIF identified by their bytes, and returns `text` with mean `confidence`. Its accepted `lang` is `eng`. The input is an image URL, so do not send it a PDF URL expecting automatic page conversion.

## Choose the reader for DOCX, PPTX or EPUB

Use `docx-to-markdown` for a DOCX document and retain its `warnings` alongside `markdown`. Conversion limitations surface as warnings rather than a promise that every element translated. The fetched body must be a ZIP containing a DOCX document; an arbitrary archive is insufficient.

Use `pptx-to-text` for ordered slide body text. Its `slides` entries preserve slide numbers and text, while `text` combines the extraction. This is a body-text reader, so do not plan on speaker notes or slide rendering. The archive must contain the expected slide XML parts.

Use `epub-to-text` for chapter text in reading order and Dublin Core metadata. Its archive container must point to an OPF package. `max_chapters` selects leading XHTML or HTML spine chapters; a longer book is cut and reported as `truncated`. Keep `chapters` when chapter boundaries matter instead of using only the combined `text`.

## Extract tabular data without assuming completeness

Use `xlsx-to-json` for XLSX rows, with dates returned as ISO strings. Set `sheet` to an exact worksheet name, or omit it to return every worksheet. `header_row` selects the column-name row; setting it to `0` returns positional arrays and `columns` set to `null`. `max_rows` limits each worksheet separately, with truncation reported per sheet.

Use `csv-to-json` for UTF-8 CSV or TSV, including quoted fields, embedded newlines and escaped quotes. The delimiter is detected from the first rows unless supplied. `header` chooses keyed objects or arrays; header names are trimmed, blank names replaced and duplicates made unique. A UTF-8 BOM is accepted, but unsupported charset declarations, NUL bytes and malformed UTF-8 are rejected. A truncated success does not validate the entire CSV structure.

## Services covered

| Endpoint | Price | Timeout | max_timeout_seconds | Size cap | Max duration |
| --- | --- | --- | --- | --- | --- |
| [csv-to-json](https://grist.tools/docs/csv-to-json) | $0.005 | 30 s | 51 | 25 MB (26,214,400 bytes) | - |
| [docx-to-markdown](https://grist.tools/docs/docx-to-markdown) | $0.005 | 40 s | 61 | 25 MB (26,214,400 bytes) | - |
| [epub-to-text](https://grist.tools/docs/epub-to-text) | $0.005 | 45 s | 66 | 25 MB (26,214,400 bytes) | - |
| [html-to-pdf](https://grist.tools/docs/html-to-pdf) | $0.005 | 12 s | 33 | 5 MB (5,242,880 bytes) | - |
| [json-to-csv](https://grist.tools/docs/json-to-csv) | $0.005 | 30 s | 51 | 25 MB (26,214,400 bytes) | - |
| [markdown-to-pdf](https://grist.tools/docs/markdown-to-pdf) | $0.005 | 12 s | 33 | 2 MB (2,097,152 bytes) | - |
| [ocr-image-to-text](https://grist.tools/docs/ocr-image-to-text) | $0.005 | 45 s | 66 | 10 MB (10,485,760 bytes) | - |
| [pdf-merge](https://grist.tools/docs/pdf-merge) | $0.005 | 45 s | 66 | 8 MB (8,388,608 bytes) | - |
| [pdf-metadata](https://grist.tools/docs/pdf-metadata) | $0.005 | 25 s | 46 | 25 MB (26,214,400 bytes) | - |
| [pdf-split](https://grist.tools/docs/pdf-split) | $0.005 | 30 s | 51 | 25 MB (26,214,400 bytes) | - |
| [pdf-to-markdown](https://grist.tools/docs/pdf-to-markdown) | $0.005 | 40 s | 61 | 25 MB (26,214,400 bytes) | - |
| [pdf-to-text](https://grist.tools/docs/pdf-to-text) | $0.005 | 40 s | 61 | 25 MB (26,214,400 bytes) | - |
| [pptx-to-text](https://grist.tools/docs/pptx-to-text) | $0.005 | 40 s | 61 | 25 MB (26,214,400 bytes) | - |
| [xlsx-to-json](https://grist.tools/docs/xlsx-to-json) | $0.005 | 40 s | 61 | 25 MB (26,214,400 bytes) | - |

## Inspect and select PDFs before extracting

Use `pdf-metadata` when the agent needs page count, document-info fields, version or the encryption flag. It reads these without rendering and can describe an encrypted PDF without decrypting it. Treat the metadata as inspection data, not extracted document text.

Use `pdf-split` to make a new PDF from `ranges`. Page numbering starts at the first page; comma-separated selections and inclusive ranges are emitted in the written order, including repeats. Descending ranges and pages beyond the end are errors. Use `pdf-merge` to concatenate source PDFs in the order of `urls`; sources are fetched sequentially. Both refuse encrypted sources and return `pdf_base64` with page and byte counts. Neither call replaces a text-extraction step.

## Render a deliverable or export rows

Choose `html-to-pdf` for an HTML or XHTML URL, or provide self-contained `html`. Supply exactly one source. JavaScript is disabled, external images, stylesheets and fonts are blocked, and inline PNG data images are supported. Build the input around those restrictions instead of expecting a page dependent on external resources to render fully.

Choose `markdown-to-pdf` for a UTF-8 Markdown URL or inline `markdown`, again supplying exactly one source. Raw HTML is escaped. PNG, JPEG, GIF and WebP data-image syntax is accepted; SVG data images and external image loading are blocked. Both renderers accept `format` and `landscape` and return `pdf_base64` with a page count.

Choose `json-to-csv` for a public UTF-8 JSON document containing an object or an array of objects. `columns` fixes column order; otherwise columns are inferred from rows retained by `max_rows`. Nested values are JSON-encoded. The output uses CSV quoting and CRLF record separators, but it does not neutralize spreadsheet formulas. Headers and strings preserve formula prefixes, tabs and carriage returns; use spreadsheet-specific import controls for untrusted data.

## Chain calls through their actual input contracts

For a PDF reading pipeline, inspect with `pdf-metadata` if page count or encryption affects your decision, then call `pdf-to-markdown` on the source URL. Compare `total_pages`, `extracted_pages` and `truncated`, and inspect `markdown` itself. Here `truncated` reports only the `max_pages` limit: a false value does not certify complete text extraction.

When you need selected pages first, insert `pdf-split`. Its `pdf_base64` is output data, while the extractor expects a public URL. Your pipeline must decode and make the resulting PDF available at a public URL before submitting the extraction request. The same handoff applies after `pdf-merge`; do not treat base64 output as an automatically hosted document.

A DOCX conversion can feed its returned `markdown` directly into the inline input of `markdown-to-pdf`. For an XLSX export, select the returned worksheet rows and make that JSON available at a public URL for `json-to-csv`. Preserve warnings, chapter or slide boundaries, and truncation indicators with the extracted content so the agent can decide whether its next task has enough input.

## Budget each successful call and its deadline

A PDF inspection and Markdown extraction costs $0.005 plus $0.005 when both calls succeed. Adding page selection adds $0.005. A DOCX extraction followed by PDF rendering costs $0.005 plus $0.005; budget image OCR separately at $0.005 per successful call. Use the table for other branches of your pipeline.

Payment uses x402 in USDC on Base. Without `payment-signature`, a call answers HTTP 402 with the price (`amount`, in atomic units of the asset) and `maxTimeoutSeconds` before payment; the free `/schema` route reports it as `max_timeout_seconds`. For `pdf-to-markdown`, the handler timeout is 40 s, the input cap is 25 MB, and the whole-call allowance in seconds is 61. Size the client deadline around the whole-call allowance, which includes verification and settlement.

Payment is verified before the handler and settled only after success. Gate refusals and handler failures are never settled. A settlement call that fails without answering or an answer that fails validation (that case is HTTP 500 `internal`, with a message starting "Payment settlement returned") leaves an uncertainty identified in the error message; inspect that message before deciding to repeat a paid request.

## Retry according to the error

Correct `invalid_input` against the schema before retrying. `blocked_target` means the network guard refused the destination, such as a disallowed address, unsupported URL scheme or port, or credentials in the URL. Repeating the same destination does not address that cause. For `unsupported_content_type`, supply a supported document type; for `unprocessable`, check `details`: document endpoints also return it when the target answered with an HTTP error status (`details.status`), otherwise it covers bytes that arrived but could not be processed, such as a malformed or encrypted document.

`too_large` means the response exceeded its streaming size cap or decompression ratio, or the document exceeded a processing limit of the endpoint, such as pixel count, slide or worksheet count, the CSV parsing budget, the PDF text extraction limit or the output PDF size. Change the source accordingly. `unreachable_target` means resolution failed, or the connection failed or closed before the body arrived; `upstream_timeout` means the destination did not answer within the declared timeout. Check source availability before scheduling another attempt.

`rate_limited` is HTTP 429 for excessive calls from a payer or towards a destination domain, with nothing charged. Reduce that traffic. Retryable HTTP 503 errors include `concurrency_limit`, `registry_at_capacity` and `upstream_unavailable`; wait the seconds specified by `retry-after`. When `upstream_unavailable` comes from the front proxy, the call may already have run and settled; check `authorizationState` before paying again. An `internal` error is a service fault, with nothing charged in almost every case; preserve its message, especially any settlement uncertainty.

## Questions

Q: Does PDF text extraction perform OCR?
A: Neither `pdf-to-text` nor `pdf-to-markdown` performs OCR; both extract the existing text layer. `ocr-image-to-text` accepts supported image URLs and returns text with mean confidence, using `eng` as its accepted language.

Q: Does a successful PDF response mean all text was extracted?
A: No: unavailable predefined character mappings can produce empty or partial text without an error. `truncated` reports only the `max_pages` limit, so inspect the returned content even when it is false.

Q: How do I select a worksheet from an XLSX file?
A: Pass its exact name in `sheet` to `xlsx-to-json`; omitting that field returns every worksheet. An unknown name produces HTTP 422 listing available names. `max_rows` applies separately to each returned worksheet.

Q: Can an agent pass extracted Markdown directly to PDF rendering?
A: Yes, pass the extracted string as `markdown` to `markdown-to-pdf`, without also supplying `url`. Raw HTML is escaped, and external images and SVG data images are blocked.

Q: Can these PDF utilities decrypt an encrypted document?
A: `pdf-metadata` describes an encrypted PDF without decrypting it. `pdf-split` and `pdf-merge` refuse encrypted sources, so metadata inspection does not make those files eligible for transformation.

Q: Does CSV export protect against spreadsheet formulas?
A: `json-to-csv` returns raw CSV without spreadsheet formula protection. Quoting handles delimiters, quotes and newlines while formula prefixes remain intact; use spreadsheet-specific import controls when handling untrusted data.

Q: Are failed document calls charged?
A: Gate refusals and failures inside the handler are never settled. Payment settlement follows handler success, but if a settlement call fails without answering or its answer fails validation (that case is HTTP 500 `internal`, with a message starting "Payment settlement returned"), its outcome cannot be stated in advance. The error message identifies that uncertainty.

This page as HTML: https://grist.tools/guides/document-parsing-api. Every page of grist.tools has a Markdown version at its address plus .md.
