Download API (API key)

Use this HTTP API to download YouTube videos from your own scripts and integrations.

Base URL — Your deployment origin, e.g. https://ytdl.my (all paths are relative to it).

API key — Create an API key in the Dashboard after you have an active subscription. Treat it like a password; do not commit it to source control.

OpenAPI — Machine-readable spec: /openapi.yaml

Authentication

Send your key on every request that requires it:

Header	Example
`X-API-Key`	`X-API-Key: ytdl_…`
`Authorization`	`Authorization: Bearer ytdl_…`

`GET /healthz` and `GET /api/healthz`

Optional liveness check. No API key.

200 — Service is up (typically { "ok": true }).

`POST /api/v1/jobs`

Starts a download job. The request may stay open until processing finishes (long-running).

Headers: Content-Type: application/json, plus your API key.

Body:

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "minutes": 20
}

Field	Required	Description
`url`	Yes	YouTube watch or `youtu.be` URL (10–2000 characters).
`minutes`	No	Omit or use `0` for full length (within plan limits). Otherwise clip to the first N minutes.

200 — Success body includes a download_url pointing at this same host (/api/v1/d?…). Example shape:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "minutes": 20,
  "download_url": "https://your-host.example.com/api/v1/d?job_id=…&e=…&s=…",
  "error": null
}

If extraction fails, you may still get 200 with status: "failed" and error set, or 502 from the gateway.

Status	Meaning
400	Invalid JSON or fields
401	Missing or invalid API key
402	No active subscription or monthly quota used up
502	Upstream download/extraction error

`GET /api/v1/jobs/{job_id}`

Poll job status with the same API key.

200 — Job object (job_id, status, download_url when ready, error, etc.).

401 — Invalid API key.

`GET /api/v1/d`

No API key. Call the exact download_url returned by the job API (signed query: job_id, e, s). Do not build this URL by hand.

200 — File stream (Content-Disposition: attachment).

403 — Link expired or signature invalid.

404 — File no longer available.

Quotas

Successful downloads count against your plan’s monthly limit. Typical tiers:

Plan	Downloads / month (approx.)
Starter	150
Growth	1500
Scale	15000

Exact limits and billing period apply as shown in your account.

Example (`curl`)

Replace BASE and KEY, then use the download_url from the JSON (or curl/wget it directly).

curl -sS -X POST "$BASE/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","minutes":0}'

Notes

The internal extractor service URL is not public; you only talk to this app.
Keep your API key secret; revoke unused keys from the Dashboard.

Download API (API key)

Authentication

GET /healthz and GET /api/healthz

POST /api/v1/jobs

GET /api/v1/jobs/{job_id}

GET /api/v1/d