API reference
Authentication
Authenticate every request with an API key (x-api-key) or a session bearer token. Keys are scoped to your account.
API keys
Create an API key in your account settings (keys are scoped to your account and shown in full only once), then send it on every request as the x-api-key header. Keys start with mdai_.
Verify a key — GET the authenticated account
curl https://api.markitdown.ai/me \ -H "x-api-key: mdai_…"
A browser session can authenticate instead with Authorization: Bearer <token>. Use API keys for server-to-server calls.
Scopes
A key can be restricted to a subset of scopes. With no scopes specified, a key gets full access. Available scopes:
Scopes
read | scope | GET endpoints — jobs, usage, files, pipelines. |
convert | scope | Upload files and start conversions. |
pipelines | scope | Create, run, and manage pipelines (batch). |
keys | scope | Manage API keys. |
webhooks | scope | Manage outbound webhook endpoints. |
billing | scope | Create checkout and portal sessions. |
Treat API keys like passwords. If a key leaks, revoke it (DELETE /keys/{id}) and create a new one.