---
title: "Convert"
description: "POST /v1/convert/{name} inputs, options, wait behaviour, the response envelope, and the full name catalog."
url: https://markitdown.ai/docs/convert
updated: 2026-09-28
source: markitdown.ai
---

# Convert

> POST /v1/convert/{name} inputs, options, wait behaviour, the response envelope, and the full name catalog.

## Request

**POST** `/v1/convert/pdf` — Convert an uploaded PDF — every `name` below follows the same request/response shape

**Body — send exactly one input kind**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | multipart | no | Raw file bytes (up to 100 MB). |
| `files` | multipart[] | no | Several files of the same `name`. |
| `url / urls` | string | no | Public http(s) page(s) — `url`/`url` name only. |
| `text / texts` | string | no | Inline content — `html`, `text`, and `markdown/*` names only. |
| `file / files` | string | no | A `file_…` id from an earlier conversion's source or output. |
| `upload / uploads` | string | no | An `upl_…` id from a completed `POST /v1/uploads` (for a file over the multipart size limit). |

**Options (top-level body fields, or multipart form fields)**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `formats` | string[] | no | Any of `markdown` (always produced), `text`, `html`, `pages`. |
| `pages` | string | no | 1-based page range, e.g. `1-5,8`. Only those pages are parsed and charged (`pdf`, `word`, `powerpoint`). |
| `quality` | string | no | `fast`, `standard`, or `max` — the processing route. |
| `ocr` | boolean | no | Force OCR on a PDF. |
| `table_mode` | string | no | `fast` or `accurate` table extraction. |
| `image_mode` | string | no | `image` name only: `ocr` (default) or `understand` (AI image understanding). |
| `figures` | string | no | `placeholder` (default) or `describe` (AI figure captions). |
| `links` | string | no | `markdown/text` only: `text-url` (default) or `text`. |
| `render` | string | no | `url` only: `auto` (default) renders the page in a headless browser when the fetched HTML has no readable content, `force` always renders, `skip` never renders. |
| `frontmatter` | boolean | no | `url` only: prepend YAML front matter with the source URL, canonical URL, title, and — when the page declares them — author, publish date, description, site name, language, and lead image. |
| `store` | boolean | no | Keep the result in your library. Default `false`: results are deleted after 24 hours. |
| `metadata` | object | no | Your own key/value data, echoed back on the conversion. |

## Waiting and 202 responses

Each call waits up to 60 seconds for every source file to finish. Change that with `Prefer: wait=N` or `?wait=N` (at most 100); `Prefer: respond-async` returns 202 at once.

**async_reason on a 202**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `wait_timeout` | reason | no | At least one source file was still running when the wait window ended. |
| `too_many_sources` | reason | no | More than 10 source files in one submission; queued without waiting. |
| `pages_exceed_sync_limit` | reason | no | A source needs more than 30 OCR pages (scanned PDFs, images) or 300 text pages; queued without waiting. |
| `capacity` | reason | no | The interactive queue is busy; the conversion runs in the background. |
| `respond_async` | reason | no | You asked for an immediate 202. |

## Response envelope

- `id` (`cnv_…`), `object` (`conversion`), `name`, `status` (`queued`, `running`, `completed`, `completed_with_errors`, `failed`), `async_reason`, `created_at`, `completed_at`.
- `summary` — `sources`, `queued`, `running`, `completed`, `failed` counts, read live from the underlying work.
- `files` — up to 100 source files (`files_next_cursor` pages the rest), each `id` (`file_…`), `status`, `pages`, `credits`, `error`, and an `outputs[]` array. `outputs[].content` is the Markdown/text/HTML inlined when it is at most 256 KB; larger outputs and `pages` output are fetched from `GET …/files/{file_id}/content`.
- `usage` — `credits_charged`, `credits_reserved` while running, and `credits_remaining`.
- `metadata`, `links` (`self`, `files`, `events`).

## The name catalog

Each `name` is its own endpoint. It accepts only its own input kinds and options (§ above), and rejects a mismatched file with `415 input_format_mismatch` before creating anything. `GET /v1/formats` returns this same table as JSON.

- **POST** [/v1/convert/pdf](/docs/api/convert-pdf) — .pdf
- **POST** [/v1/convert/word](/docs/api/convert-word) — .doc .docx .odt .rtf
- **POST** [/v1/convert/powerpoint](/docs/api/convert-powerpoint) — .ppt .pptx .odp
- **POST** [/v1/convert/excel](/docs/api/convert-excel) — .xls .xlsx .ods .csv
- **POST** [/v1/convert/epub](/docs/api/convert-epub) — .epub
- **POST** [/v1/convert/image](/docs/api/convert-image) — .png .jpg .jpeg .webp .gif .bmp .tif .tiff
- **POST** [/v1/convert/html](/docs/api/convert-html) — .html .htm or inline text
- **POST** [/v1/convert/text](/docs/api/convert-text) — .txt .md or inline text
- **POST** [/v1/convert/url](/docs/api/convert-url) — public URL
- **POST** [/v1/convert/markdown/html](/docs/api/convert-markdown-html) — 0 credits
- **POST** [/v1/convert/markdown/text](/docs/api/convert-markdown-text) — 0 credits

## How are conversion credits charged?

Standard pages and OCR pages cost 1 credit per page. Credits are reserved per source file when it starts and settled from the pages actually parsed, so `pages` lowers the cost of a long document. A failed file is not charged. If your balance cannot cover the reservation for every source in the request, the whole call returns `402 insufficient_credits`; a file above your plan's page cap returns `422 page_cap_exceeded` before anything runs. Rendering (`markdown/html`, `markdown/text`) is always 0 credits.

## How many conversions can run at once?

Waiting calls are limited per account: Lite 3, Pro 5, and Max 8 at a time. Another call beyond that returns `429 concurrency_limited`; retry after one finishes, or send `Prefer: respond-async` and poll. There is no separate limit on background (non-waiting) work — put many files in one request instead of many parallel calls.

## Related

- [Conversions](https://markitdown.ai/docs/conversions)
- [Batches](https://markitdown.ai/docs/batches)
- [Conversion Files](https://markitdown.ai/docs/files)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)