# The document-to-Markdown API

> Convert documents from your own code. Submit a file over HTTPS with an API key, poll the job or receive a webhook, and feed clean Markdown into RAG pipelines, agents, and internal tools.

## How it works

- Create an API key and send it in the x-api-key header.
- Upload a file, then POST /convert — accepted asynchronously, returns a job.
- Poll the job, or subscribe to job.completed and job.failed webhooks.
- Pipe the returned Markdown into ingestion jobs, agents, and downstream systems.

## Request

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

## Built for automation

- Convert endpoint — a single POST to /convert starts a job for any supported format.
- API keys — per-account keys sent via the x-api-key header.
- Webhooks — subscribe to job.completed and job.failed instead of polling.
- Async jobs — conversions run in the background; large documents never block a request.

## 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.

## FAQ

### 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.