Markdown Anything

How document-to-Markdown conversions work — sync and async modes, status lifecycle, and auto-refunds.

A conversion transforms a file from its original format into clean, structured Markdown. You can convert files through the dashboard or the API.

Sync vs Async

Markdown Anything supports two conversion modes:

Sync conversions return the Markdown directly in the API response. Best for small files where you need the result immediately.

curl -X POST https://markdownanything.com/api/v1/convert \
  -H "Authorization: Bearer mda_your_token" \
  -F "[email protected]"

The response includes the converted markdown, credits used, and remaining balance.

Async conversions process the file in the background and deliver the result via webhook. Best for large files or batch processing.

curl -X POST https://markdownanything.com/api/v1/convert \
  -H "Authorization: Bearer mda_your_token" \
  -F "[email protected]" \
  -F "webhook_url=https://your-app.com/webhooks/conversion"

You receive a conversion ID immediately and the result is delivered to your webhook URL when processing completes.

Conversion Lifecycle

Every conversion moves through a defined set of statuses.

Pending

The conversion is created and queued. Credits are deducted upfront. The file is uploaded to temporary storage.

Processing

The conversion engine picks up the job. The file is read, parsed, and converted to Markdown. If Enhanced AI is enabled, AI-powered extraction runs during this stage.

Completed

Conversion succeeded. The Markdown output is available for download or delivery. If a webhook URL was provided, the result is delivered automatically.

Failed

Something went wrong during processing. The error message is recorded, credits are automatically refunded, and your webhook (if configured) is notified of the failure.

Auto-Refund on Failure

If a conversion fails after all retry attempts, the credits charged for that conversion are automatically refunded to your workspace balance. The refund amount matches the original charge:

Standard conversion: 1 credit refunded
Enhanced AI conversion: 2 or 3 credits refunded (depending on your plan)

Refunds happen automatically. You do not need to contact support or take any manual action.

Retry Behavior

Async conversions are retried automatically before being marked as failed. Sync conversions do not retry — if processing fails, the error is returned immediately.

Webhook Delivery

When you provide a webhook_url, the conversion result is delivered via POST request after processing completes. Webhooks are delivered for both successful and failed conversions.

You can optionally provide a webhook_secret to verify webhook authenticity.
If initial delivery fails, delivery is retried.
You can check webhook delivery status from the dashboard or API.

Options

Each conversion supports several optional parameters:

Parameter	Description	Default
`enhanced_ai`	Use AI-powered extraction for scanned documents, images, audio, and complex content.	Workspace default
`optimize_tokens`	Post-process markdown to minimize token count.	Workspace default
`include_metadata`	Include document metadata (page count, word count, etc.) in the response.	`false`
`webhook_url`	URL to receive the conversion result (enables async mode).	—
`webhook_secret`	Secret for verifying webhook signatures.	—

Next Steps

Enhanced AI — AI-powered extraction for complex content
Token Optimization — Reduce output size for LLM pipelines
Supported Formats — All file types you can convert

Conversions