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:
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 carriesX-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.