REST API
Build your own download flow
Three JSON endpoints with consistent responses. No API key — each job returns an access token that scopes status requests to that job.
Reference
Endpoints
- GET
/api/v1/public-info?url=YOUTUBE_URLVideo title, channel, duration, thumbnail, available MP4 qualities, and whether audio is available.
- POST
/api/v1/public-convertStart a conversion. Body: url, kind (mp3 or mp4), and quality. Returns the job and an access token.
- GET
/api/v1/public-jobs/{job_id}?token=ACCESS_TOKENJob status, progress, current step, and the download_url once the file is ready.
Step 1
Create a conversion
Use a quality returned by public-info: a resolution for mp4, or a bitrate (64–320) for mp3.
Create a conversion
const res = await fetch("https://ytubego.local/api/v1/public-convert", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
url: "https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID",
kind: "mp3",
quality: 192
})
});
const { data, access_token } = await res.json();Step 2
Poll a job
Poll about once per second with the access token until the job is ready or failed.
Wait for the file
async function waitForFile(jobId, token) {
while (true) {
const res = await fetch(
`https://ytubego.local/api/v1/public-jobs/${jobId}?token=${token}`
);
const { ok, data, error } = await res.json();
if (!ok) throw new Error(error);
if (data.status === "ready") return data.download_url;
if (data.status === "failed") throw new Error(data.error_message);
await new Promise((r) => setTimeout(r, 1000));
}
}Lifecycle
Job statuses
queued- Waiting for a worker. queue_position may be set.
processing- Downloading, converting, or uploading. Check progress and current_step.
ready- Finished. download_url points to the file.
failed- Stopped. error_code and error_message explain why.
Handling
Errors
Every response includes ok. When it is false, show error to the user and let them retry; error_code is stable for programmatic checks.
Error response
{
"ok": false,
"error": "Human-readable explanation",
"error_code": "MACHINE_READABLE_CODE"
}