Core
Convert
POST /v1/convert/{name} inputs, options, wait behaviour, the response envelope, and the full name catalog.
Request
https://api.markitdown.ai/v1/convert/pdfConvert an uploaded PDF — every name below follows the same request/response shapefile | multipart | Raw file bytes (up to 100 MB). |
files | multipart[] | Several files of the same name. |
url / urls | string | Public http(s) page(s) — url/url name only. |
text / texts | string | Inline content — html, text, and markdown/* names only. |
file / files | string | A file_… id from an earlier conversion's source or output. |
upload / uploads | string | An upl_… id from a completed POST /v1/uploads (for a file over the multipart size limit). |
formats | string[] | Any of markdown (always produced), text, html, pages. |
pages | string | 1-based page range, e.g. 1-5,8. Only those pages are parsed and charged (pdf, word, powerpoint). |
quality | string | fast, standard, or max — the processing route. |
ocr | boolean | Force OCR on a PDF. |
table_mode | string | fast or accurate table extraction. |
image_mode | string | image name only: ocr (default) or understand (AI image understanding). |
figures | string | placeholder (default) or describe (AI figure captions). |
links | string | markdown/text only: text-url (default) or text. |
render | string | 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 | 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 | Keep the result in your library. Default false: results are deleted after 24 hours. |
metadata | object | 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.
wait_timeout | reason | At least one source file was still running when the wait window ended. |
too_many_sources | reason | More than 10 source files in one submission; queued without waiting. |
pages_exceed_sync_limit | reason | A source needs more than 30 OCR pages (scanned PDFs, images) or 300 text pages; queued without waiting. |
capacity | reason | The interactive queue is busy; the conversion runs in the background. |
respond_async | reason | 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,failedcounts, read live from the underlying work.files— up to 100 source files (files_next_cursorpages the rest), eachid(file_…),status,pages,credits,error, and anoutputs[]array.outputs[].contentis the Markdown/text/HTML inlined when it is at most 256 KB; larger outputs andpagesoutput are fetched fromGET …/files/{file_id}/content.usage—credits_charged,credits_reservedwhile running, andcredits_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.pdf
- POST/v1/convert/word.doc .docx .odt .rtf
- POST/v1/convert/powerpoint.ppt .pptx .odp
- POST/v1/convert/excel.xls .xlsx .ods .csv
- POST/v1/convert/epub.epub
- POST/v1/convert/image.png .jpg .jpeg .webp .gif .bmp .tif .tiff
- POST/v1/convert/html.html .htm or inline text
- POST/v1/convert/text.txt .md or inline text
- POST/v1/convert/urlpublic URL
- POST/v1/convert/markdown/html0 credits
- POST/v1/convert/markdown/text0 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.
Sources and specs: RFC 9110: HTTP Semantics · RFC 7763: The text/markdown Media Type