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.

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://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://mdkit.online/v1/jobs/$JOB_ID
curl -H "X-API-Key: $MDKIT_API_KEY" \
  "https://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.