API reference

Quickstart

Convert your first document end to end: upload, inspect cost, convert, poll, and read the Markdown.

The conversion flow

Request an upload URL and upload the file bytes to storage.
Inspect the file to preview pages, route, and credit cost.
Start the conversion job.
Poll the job (or receive a webhook) until it completes.
Read the Markdown from the job result.

1. Upload the file

POSThttps://api.markitdown.ai/files/upload-urlGet a presigned URL, then PUT the bytes to it

curl https://api.markitdown.ai/files/upload-url \
  -H "x-api-key: mdai_…" -H "content-type: application/json" \
  -d '{"name":"report.pdf","mime":"application/pdf","bytes":248120}'

# -> { "fileId": "…", "putUrl": "https://…", "r2Key": "…" }
# Upload the raw bytes to putUrl:
curl -X PUT "<putUrl>" --data-binary @report.pdf

2. Inspect, then convert

POST /files/inspect returns reservedCredits for the file. Pass that as estimatedCredits when you start the job.

curl https://api.markitdown.ai/convert \
  -H "x-api-key: mdai_…" -H "content-type: application/json" \
  -H "Idempotency-Key: convert-report-001" \
  -d '{"fileId":"…","estimatedCredits":3}'

# -> a conversion job

3. Poll and read the Markdown

# Poll until status is "completed"
curl https://api.markitdown.ai/jobs/<jobId> -H "x-api-key: mdai_…"

# Read the converted Markdown
curl https://api.markitdown.ai/jobs/<jobId>/result -H "x-api-key: mdai_…"

Prefer webhooks over polling for production: subscribe to job.completed and job.failed (see Webhooks).

PreviousAuthentication Next Convert