Skip to main content
The REST API is what the MCP server uses under the hood, and what your app calls in production. Every endpoint page here has a Try it button that sends a real request with your key.
Try it runs real jobs and spends real credits. An import costs at least $0.03. Status checks and GET /balance are free.

Base URL

Authentication

Send your API key as a Bearer token on every request. Get it from the API key page, and keep it on your server.

Responses

Every response uses the same envelope. On success:
On failure, with the HTTP status set to match:
More detail, and every rate limit, is on Errors & rate limits.

Jobs are async

1

Start a job

POST /import, /transcribe, /metadata, or /metadata/basic returns a jobId immediately.
2

Wait for the result

Pass webhookUrl and Importly POSTs the result to you when the job succeeds, with the fields directly on data. Or poll the matching /status?id= endpoint every few seconds, where the fields are under result.
3

Handle failures

A failed job has status: "failed", a message, and usually a code. Failed jobs don’t send webhooks, so keep polling as a fallback.

Limits

Limits apply per API key, per hour: 240 imports, 240 transcriptions, 1,000 metadata requests, 3,600 status checks per job type, and 600 balance checks. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Window headers.

OpenAPI spec

The full spec is at /docs/openapi.yaml. Point a client generator or your coding agent at it.