Authentication
Every request carries your API key as a bearer token in the Authorization header. There is no session, no cookie and no OAuth dance — one header on every call.
Keys are secrets. They belong on a server, in an environment variable. A key shipped in browser JavaScript or a mobile bundle is public the moment it ships, and anyone who reads it can spend your quota.
- 1
Store the key server-side
Put it in an environment variable your server reads at runtime. Never commit it, and never reference it from client code.
- 2
Send it as a bearer token
Set `Authorization: Bearer <your key>` on every request. A missing or malformed key returns 401.
- 3
Proxy from your own backend
If a browser or app needs this data, call your backend and have it call the API. That keeps the key server-side and lets you apply your own limits.
POST /v1/analyze — inspect before committing
Analyze takes a URL and returns what is actually available: the title, the duration, and the renditions the source offers. It does not produce a file.
This is the call to make first in almost every flow. It is how you find out whether a link resolves at all, and it lets you show a user real options instead of guessing which formats exist.
POST /v1/download — request the file
Download returns metadata plus a download URL for the rendition you asked for. Fetch that URL to get the bytes.
Treat the returned URL as short-lived and single-purpose. Request it when you are ready to use it rather than storing it and hoping it still resolves later.
GET /v1/usage — know where you stand
Usage reports your consumption against your quota. Polling it occasionally is far better than discovering your limit by being rejected mid-job.
It is also the honest way to build a dashboard for your own users, rather than counting requests yourself and drifting out of sync.
Common questions
- Do I need to call analyze before download?
- Not technically, but you almost always should. Analyze tells you which renditions exist, so download can request one that is actually available rather than failing on a guess.
- Can I call the API from the browser?
- You should not. It would expose your key to anyone who opens developer tools. Proxy through your own backend instead.