Conversions API

The same conversion engine behind the mdedit.ai web tools (opens in a new tab) is available programmatically: Pandoc-quality format conversion with tables, math, and Mermaid surviving the round trip. One engine, three channels:

• REST — the /conversions endpoints documented here
• CLI — mdedit convert (npx mdedit-cli convert README.md --to docx)
• Agents — the convert_document tool in the mdedit MCP server

All three draw from the same quota. REST calls authenticate with an API key carrying the conversions:execute scope; the CLI can use a key or the browser sign-in (mdedit auth login), which mdedit convert offers automatically on an interactive first run.

Quickstart

Base URL: https://apiv2.mdedit.ai/api. Send your key as an x-api-key header.

1. Get an upload URL — input keys have the form tools/input/<uuid>/<filename>. Generate a fresh UUID per conversion: the queue job ID is derived from this key, so reusing one returns 409 once the job exists.

KEY="tools/input/$(uuidgen | tr '[:upper:]' '[:lower:]')/README.md"
curl -X POST https://apiv2.mdedit.ai/api/conversions/uploads \
  -H "x-api-key: $MDEDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"$KEY\", \"action\": \"putObject\", \"contentType\": \"text/markdown\"}"

2. Upload the file to the returned signedUrl (valid for 5 minutes):

curl -X PUT "<signedUrl>" -H "Content-Type: text/markdown" --data-binary @README.md

3. Start the conversion — conversion is asynchronous and returns a jobId:

curl -X POST https://apiv2.mdedit.ai/api/conversions \
  -H "x-api-key: $MDEDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"pandoc\", \"inputKey\": \"$KEY\", \"inputFormat\": \"markdown\", \"outputFormat\": \"docx\"}"

4. Poll until it completes, then download:

curl https://apiv2.mdedit.ai/api/conversions/<jobId> -H "x-api-key: $MDEDIT_API_KEY"
# when status is "completed":
curl -OJ https://apiv2.mdedit.ai/api/conversions/<jobId>/download -H "x-api-key: $MDEDIT_API_KEY"

Conversion types: pandoc (general format conversion), pdf (Markdown/HTML to PDF), zip (Markdown with assets), mp3 (text-to-speech; paid plans), and markitdown (Office/document imports to Markdown). Inputs are capped at 10 MB (50 MB for LaTeX project archives).

The full request and response schemas are in the interactive API reference (opens in a new tab) (OpenAPI spec: swagger.json (opens in a new tab)).

Quotas

Programmatic conversions are metered per calendar month per account, with a per-credential daily burst cap. The monthly meter is shared across every key, CLI session, and MCP client on the account.

A request over quota returns 403 with the quota state and reset time in the body. Current usage is visible in Settings → Subscription.

Need more than Premium's ceiling? Contact us (opens in a new tab) — higher-volume access is provisioned case by case.

Errors