API

The document-to-Markdown API

Convert documents from your own code. Send a file, get clean Markdown back, and wire it into RAG ingestion, agents, and internal tools.

View pricing

Submit conversion jobs over HTTPS with an API key
Poll for results or receive a webhook callback
Same parsing engine as the web app

POST /convert

curl https://api.markitdown.ai/convert \
  -H "x-api-key: mdai_…" \
  -H "content-type: application/json" \
  -d '{"fileId":"…","estimatedCredits":3}'

202 Accepted · job.completed → Markdown

How it works

Four steps from key to Markdown. The flow is async by design, so long conversions never tie up a request.

Create an API key

Generate a key in your account settings and send it in the x-api-key header.

Submit a document

POST a file to /convert. The request is accepted asynchronously and returns a job.

Poll or get a webhook

Check the job status, or subscribe to job.completed and job.failed events.

Use the Markdown

Pipe the result straight into ingestion jobs, agents, and downstream systems.

Response and webhooks

A convert request returns a job to poll, and fires a webhook when it settles. The converted Markdown is read from the completed job.

Submit, then poll the job

# 202 Accepted
{ "jobId": "job_a1b2c3", "status": "queued" }

# GET /v1/jobs/job_a1b2c3
{ "job": { "id": "job_a1b2c3", "status": "completed" } }

Webhook — job.completed

POST https://your-app.example.com/webhooks
{
  "type": "job.completed",
  "data": { "jobId": "job_a1b2c3", "status": "completed" }
}

Subscribe to job.completed and job.failed so you can react the moment a conversion settles instead of polling.

Built for automation

Convert endpoint

A single POST to /convert starts a job for any supported document format.

API keys

Per-account keys sent via the x-api-key header, so conversion fits any server or script.

Webhooks

Subscribe to job.completed and job.failed instead of polling for long-running jobs.

Async jobs

Conversions run in the background, so big documents never block your request.

Use cases

Where teams wire it in

RAG ingestion

Convert documents inside ingestion jobs before chunking and embedding.

AI agents

Let agents turn arbitrary files into clean text mid-pipeline.

Content pipelines

Feed Markdown into a CMS, docs site, or knowledge base automatically.

Internal tools

Add document conversion to the products and back-office tools you already run.

Auth, usage, and limits

API keys are scoped to your account and sent in the x-api-key header
Usage is metered with the same credits as the web app — heavier files cost more
Requests are rate limited per account to keep conversion responsive
A quality parameter selects the processing route for each conversion

Common questions

How do I authenticate?

Create an API key in your account and send it in the Authorization header as a Bearer token. Keys are scoped to your account.

Is conversion synchronous?

No. A convert request is accepted asynchronously and returns a job. You can poll the job for its result or receive a webhook when it finishes.

What events can I subscribe to?

Outbound webhooks support job.completed and job.failed, so you can react as soon as a conversion settles instead of polling.

Which plans include API access?

API access is available on paid plans. See the pricing page for current plan limits and credits.

How is API usage billed?

API conversions draw from the same credit balance as the web app, so a heavier document maps to higher usage.

Turn a document into Markdown

Free in your browser, no sign-up. Sign in for saved history, batch, and the API.

Try Free