Document conversion as an API
The engine behind mdedit.ai's converters, exposed as a REST API and wired into the CLI and MCP tools. Tables, math, and Mermaid survive the trip.
By Vivek Maskara · Last updated
POST /api/conversions
{
"type": "pandoc",
"inputKey": "tools/input/…/README.md",
"inputFormat": "markdown",
"outputFormat": "docx"
}One engine, three ways in
The same conversion service answers your backend, your shell scripts, and your AI agents. One key, one quota, identical output everywhere.
REST
Async jobs over plain HTTP: upload, convert, poll, download. Typed schemas in the OpenAPI reference.
POST https://apiv2.mdedit.ai/api/conversionsCLI
One command in a script or CI step. Formats are inferred from file extensions.
mdedit convert notes.md --to pdf --out notes.pdfAgents
The convert_document tool ships in the mdedit MCP server, listed for Claude, Cursor, and Gemini.
claude mcp add --transport stdio mdedit -- npx -y @mdedit/mcp-serverFour steps, start to finish
A conversion is an async job. Every call to the mdedit API carries an x-api-key header from a key you create in Settings. The runnable walkthrough, with full request and response schemas, lives in the docs.
Upload your file
Ask for a presigned URL, then PUT the file straight to storage.
POST /api/conversions/uploadsStart the job
Send the uploaded key plus the formats you want. You get a job ID back.
POST /api/conversionsPoll for status
Watch the job until it reports completed. Failures name the reason.
GET /api/conversions/{jobId}Download the result
Pull the converted file through the API. No S3 redirect to follow.
GET /api/conversions/{jobId}/download
Published quotas, no surprises
API conversions are metered per account each calendar month, with a per-credential daily burst cap. Standard is the plan built for developers.
| Plan | Conversions / month | Burst / day | Built for |
|---|---|---|---|
| FreeEnough to wire up and test an integration. | 25 | 10 | Enough to wire up and test an integration. |
| StandardThe developer plan. Covers scripts, CI jobs, and steady production use. | 2,500 | 250 | The developer plan. Covers scripts, CI jobs, and steady production use. |
| PremiumHeadroom for pipelines that convert at volume. | 5,000 | 500 | Headroom for pipelines that convert at volume. |
Keys can be scoped: choose Conversions only when creating one and it carries conversions:execute and nothing else. Plan pricing is on the pricing page.
Conversions API questions
How do I authenticate?
Create an API key in Settings with the conversions:execute scope and send it as an x-api-key header. The CLI and MCP server accept the same key, and all three channels draw from the same quota. See API keys.
Which formats are supported?
Markdown, HTML, and LaTeX inputs convert to Word, PDF, HTML, LaTeX, EPUB, and more through the Pandoc engine. Office documents and PDFs convert to Markdown through MarkItDown. Markdown and HTML also render to PDF directly, and Markdown bundles export as Zip with assets.
Is there a free tier?
Yes. Every account gets 25 API conversions a month with a 10-per-day burst allowance, enough to build and test an integration before paying anything.
What happens when I hit the quota?
The request returns 403 with the meter state and reset time in the body, and nothing is charged against the quota. Monthly meters reset on the calendar month; burst meters reset daily. Current usage is shown in Settings.
How long do you keep my documents?
Conversion inputs and outputs live in a private S3 bucket under the tools/ prefix, and a lifecycle rule deletes every object there 30 days after it is written. Nothing is public, and download URLs are presigned and short lived.
I need more than the Premium ceiling. What are my options?
Higher-volume access is provisioned case by case while the API is in its first release. Contact us with your expected monthly volume.