When should I use the async lane instead of /v1/convert?

When the file is over the 8 MB synchronous cap, when the document is scanned or layout-heavy enough to need the high-fidelity Docling engine, or when you want structured JSON output — which the synchronous lane does not produce.

Do async jobs need an API key?

Yes. The synchronous endpoint accepts anonymous calls; the job endpoints require an X-API-Key header.

What happens if a job fails?

Its 10 credits are refunded automatically. You are not charged for a conversion you did not receive.

Should I poll or use a webhook?

Use a webhook if you have somewhere to receive it — it removes the polling loop entirely. Polling the job endpoint is the fallback when you have no public callback URL.

Async conversion jobs with polling and webhooks

Convert big or complex documents asynchronously: submit a job, poll its status or get a signed webhook, then fetch Markdown or JSON output.

Last updated 2026-07-26

Async upload cap	50 MB per file (POST /v1/convert/jobs)
Cost	10 credits per async job, refunded automatically if the job fails
Auth	API key required (X-API-Key header)

The async lane runs the high-fidelity conversion engine — built for large files, scanned PDFs and layout-heavy documents. Submit the file, get a job id back, then either poll or receive a webhook when it finishes.

Submit

curl -H "X-API-Key: $MDKIT_API_KEY" \
  -F "file=@big-report.pdf;type=application/pdf" \
  -F "webhook_url=https://your-app.example.com/hooks/mdkit" \
  https://api.mdkit.online/v1/convert/jobs

The response carries everything you need:

{
  "job_id": "…",
  "status": "queued",
  "webhook_secret": "…",
  "result_url": "/v1/convert/jobs/…/result",
  "poll_url": "/v1/jobs/…"
}

webhook_url is optional — leave it off to poll instead. When set, the completion callback is signed with the returned webhook_secret so you can verify it really came from mdkit.

Poll and fetch

curl -H "X-API-Key: $MDKIT_API_KEY" https://api.mdkit.online/v1/jobs/$JOB_ID
curl -H "X-API-Key: $MDKIT_API_KEY" \
  "https://api.mdkit.online/v1/convert/jobs/$JOB_ID/result?format=markdown"

format=json returns the structured document instead — see the JSON output guide. Jobs are strictly owner-scoped: another key's job id is a plain 404.

Try it

Try it free — the free tier includes enough credits to test the full submit → webhook → result loop.

FAQ

When should I use the async lane instead of /v1/convert?: When the file is over the 8 MB synchronous cap, when the document is scanned or layout-heavy enough to need the high-fidelity Docling engine, or when you want structured JSON output — which the synchronous lane does not produce.
Do async jobs need an API key?: Yes. The synchronous endpoint accepts anonymous calls; the job endpoints require an X-API-Key header.
What happens if a job fails?: Its 10 credits are refunded automatically. You are not charged for a conversion you did not receive.
Should I poll or use a webhook?: Use a webhook if you have somewhere to receive it — it removes the polling loop entirely. Polling the job endpoint is the fallback when you have no public callback URL.