API reference

Introduction

The markitdown.ai API converts documents (PDF, Office, images, HTML) into clean, AI-ready Markdown over HTTPS.

Overview

The markitdown.ai API turns documents into structured Markdown for LLMs, RAG pipelines, and agents. You upload a file, start a conversion job, then poll the job or receive a webhook and read the Markdown back. The same parsing engine powers the web app.

The public developer API is served from https://api.markitdown.ai. The web app's same-origin /api/* routes are reserved for internal browser and session traffic.

Conversion is asynchronous: credit-spending endpoints create a job (HTTP 200) that you poll or subscribe to via webhooks. They never block while a large document parses.

Conventions

Auth — send an API key as x-api-key, or a session token as Authorization: Bearer <token>.
JSON — request and response bodies are application/json unless noted (file bytes are uploaded directly to storage).
Idempotency — credit-spending POSTs accept an Idempotency-Key header that replays the original response on retry.
Credits — usage is metered in credits; a standard page is 1 credit, heavier routes (OCR, complex tables) cost more.

A machine-readable OpenAPI 3.1 spec is available at https://api.markitdown.ai/openapi.json (import it into Postman or generate a client).

Next Authentication