Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coah80/yoink/llms.txt

Use this file to discover all available pages before exploring further.

Yoink’s playlist feature lets you batch-download YouTube playlists as a single ZIP archive. The job runs asynchronously in the background — you start it, poll for status, and download the finished archive when it’s ready. Each video inside the ZIP is named with a zero-padded track number so your files stay in order.

​
How playlist downloads work

Behind the scenes, Yoink fetches the full playlist index via yt-dlp’s --flat-playlist mode, then iterates through each video sequentially. YouTube videos are downloaded through yt-dlp first, with Cobalt as a fallback. After each video is processed it is written into a local directory. When all videos have been attempted the entire directory is compressed into a single ZIP and a time-limited download token is issued.
1

Start the playlist job

Send a POST /api/playlist/start request with the playlist URL and your desired format options. The server responds immediately with a jobId.
POST /api/playlist/start
Content-Type: application/json

{
  "url": "https://www.youtube.com/playlist?list=PLxxxxxx",
  "format": "video",
  "quality": "1080p",
  "container": "mp4",
  "audioFormat": "mp3",
  "audioBitrate": "320",
  "clientId": "your-client-id",
  "resumeFrom": 1
}
Response:
{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }
2

Poll for status

Repeatedly call GET /api/playlist/status/{jobId} until status is complete or error. The response gives you granular per-video progress.
GET /api/playlist/status/550e8400-e29b-41d4-a716-446655440000
Example in-progress response:
{
  "status": "downloading",
  "message": "downloading 12/47: My Video Title",
  "progress": 24.8,
  "totalVideos": 47,
  "currentVideo": 12,
  "currentVideoTitle": "My Video Title",
  "videosCompleted": 11,
  "failedVideos": [],
  "failedCount": 0
}
When the job finishes, status becomes "complete" and a downloadToken field appears in the response alongside fileName and fileSize.
3

Download the ZIP

Use the downloadToken from the completed status response to retrieve your archive:
GET /api/playlist/download/{token}
The download link is valid for 12 hours after the job completes (PlaylistDownloadExp). After that the token expires and the file is deleted from the server.

​
Request parameters

FieldDefaultDescription
url—YouTube playlist URL
formatvideovideo or audio
quality1080p2160p, 1440p, 1080p, 720p, 480p, 360p
containermp4mp4, webm, mkv, mov
audioFormatmp3mp3, m4a, opus, wav, flac
audioBitrate32064, 96, 128, 192, 256, 320
clientId—Ties the job to a client for concurrency tracking
resumeFrom11-based video index to start from (see resume support)

​
Status response fields

FieldTypeDescription
statusstringstarting, downloading, zipping, complete, error
messagestringHuman-readable progress message
progressnumber0–100 overall percentage
totalVideosnumberTotal videos found in the playlist
currentVideonumberIndex of the video currently being downloaded
currentVideoTitlestringTitle of the video currently being downloaded
videosCompletednumberVideos successfully downloaded so far
failedVideosarrayObjects with num, title, and reason for each failure
failedCountnumberTotal number of failed videos
downloadTokenstringPresent when status === "complete"
fileNamestringZIP filename (e.g. My Playlist.zip)
fileSizenumberZIP file size in bytes

​
Resuming a partial download

If a previous run was interrupted or you want to skip already-downloaded videos, pass resumeFrom as the 1-based index of the first video you want to include: 
{
  "url": "https://www.youtube.com/playlist?list=PLxxxxxx",
  "resumeFrom": 26
}
Yoink will skip videos 1–25 and begin downloading from video 26. The total video count still reflects the full playlist length for context.
The maximum number of videos processed in a single run is 1,000 (MaxPlaylistVideos). For playlists larger than 1,000 videos, split the download across multiple runs using resumeFrom.

​
Stopping early

You can signal Yoink to stop downloading and immediately package the videos it has already completed: 
POST /api/finish-early/{id}
The job transitions to the zipping phase right away and produces a ZIP from the videos downloaded so far. This is useful for very long playlists where you only need the first portion.

​
ZIP file structure

Each video in the ZIP is named using a three-digit zero-padded sequence number followed by its sanitised title: 
001 - Introduction to Yoink.mp4
002 - Installing on Ubuntu.mp4
003 - Configuration Guide.mp4
…
This naming convention ensures files sort correctly in any file manager regardless of the original playlist order.

​
Failed videos

Videos that could not be downloaded (private, geo-blocked, deleted, etc.) are tracked in the failedVideos array throughout the job. The final complete response includes the full list so you know exactly which items to follow up on manually.

Finish Early

Stop a running job and package whatever has been downloaded so far by calling POST /api/finish-early/{id}.

Download Expiry

The ZIP download link expires 12 hours after the job completes. Download promptly — the file is removed from the server afterwards.
Poll the status endpoint every 2–3 seconds during active downloading. The currentVideoTitle and videosCompleted fields give a smooth real-time progress experience without hammering the server.

Build docs developers (and LLMs) love

Get started for freeTalk to us