Convert to Markdown

Convert PDFs, scans, and office files to markdown with one API call. POST /v1/documents/convert returns clean markdown plus page, table, and OCR metadata.

Convert to Markdown, POST /v1/documents/convert, is a PDF to markdown API: upload a file in a single request and get back its clean markdown representation, including tables, with OCR applied to scanned pages. It is a stateless operation: it does not create a document record, does not run field extraction, and does not touch the field registry. Use it to turn a one-off PDF, image, or office document into markdown for inspection or for your own downstream processing.

This endpoint is the complement of GET /v1/documents/{id}/markdown. That endpoint returns the stored markdown of a document that has already been ingested and processed, looked up by ID. This endpoint takes a raw file you upload in the request and returns its markdown immediately, with no persistence. Use convert for ad-hoc inspection, and the stored-markdown endpoint for documents already in your workspace.

The file is sent as multipart form data under the field name file. PDFs, images, and common document and text formats are supported. Scanned pages and images are escalated to vision OCR by default; set the vision form field to the string false to disable that escalation and rely on the native text layer only.

The response returns the rendered markdown plus conversion metadata: the detected source_format, a page_count, a table_count of tables found, the 1-based vision_pages that required vision OCR, and any warnings raised during conversion (for example an unsupported file type that fell back to a plain text decode).

Response

{
  "filename": "invoice-0847.pdf",
  "markdown": "# Invoice 0847\n\n| Item | Qty | Price |\n| --- | --- | --- |\n| Widget A | 10 | 25.00 |\n| Widget B | 4 | 60.00 |\n\n**Total:** 490.00\n",
  "source_format": "pdf",
  "page_count": 2,
  "table_count": 1,
  "vision_pages": [],
  "warnings": []
}

A common pattern is to convert a file, review the markdown and the warnings, and only then decide whether to ingest it for full extraction. Because convert never persists anything, you can run it repeatedly on the same file (for example with and without vision) without creating duplicate documents.

Errors