Download Media and Fetch Metadata from Any URL

The download endpoints are the core of Yoink. GET /api/metadata interrogates a URL and returns structured information — title, duration, thumbnail, and platform-specific flags — without downloading anything. GET /api/download performs the actual download and streams the binary result directly to the client with a Content-Disposition: attachment header. Both endpoints share URL validation logic and will return a 400 error for malformed or missing URLs. Metadata responses are cached for 10 minutes per URL (single-video mode only), so repeated calls to /api/metadata for the same link are cheap.

Progress events for long-running downloads can be tracked in real time by passing a progressId and subscribing to GET /api/progress/{progressId} (Server-Sent Events). If you omit progressId, one is generated internally and discarded.

GET /api/metadata

Returns metadata for a single video or an entire playlist without downloading any media.

GET /api/metadata?url={url}&playlist={bool}

Query Parameters

url

string

required

Fully-qualified URL of the media to inspect. Must begin with http:// or https://. Maximum length is 2048 characters.

playlist

boolean

default:"false"

When true, returns aggregated playlist metadata instead of single-video metadata. Forces a fresh yt-dlp call — the 10-minute cache is bypassed for playlist requests.

Response — Single Video

When playlist=false (the default), the server returns a JSON object describing the individual video. The exact shape varies by platform — fields marked optional are only present when applicable.

title

string

Human-readable title of the video.

ext

string

Source file extension (e.g. mp4, webm).

string

Platform-specific video identifier.

uploader

string

Channel or account name that published the video.

duration

number

Duration in seconds. May be 0 or absent if the platform does not expose it.

thumbnail

string

URL of the video thumbnail image.

isPlaylist

boolean

Always false in single-video mode.

usingCookies

boolean

true when the server used a cookies file to authenticate the yt-dlp request.

viaCobalt

boolean

Optional. true when metadata was fetched via a Cobalt API rather than yt-dlp (common for YouTube).

Show YouTube Clip fields (isClip: true)

isClip

boolean

true for YouTube /clip/ URLs.

clipStartTime

number

Clip start offset in seconds relative to the full video.

clipEndTime

number

Clip end offset in seconds relative to the full video.

clipDuration

number

Length of the clip in seconds (clipEndTime - clipStartTime).

originalVideoId

string

Video ID of the underlying full-length video.

fullVideoUrl

string

URL of the full video that will be downloaded and trimmed.

Show TikTok Slideshow fields (isSlideshow: true)

isSlideshow

boolean

true when the TikTok post is an image carousel / slideshow.

imageCount

number

Number of images in the slideshow.

Show gallery-dl fallback fields (isGallery: true)

isGallery

boolean

true when metadata was retrieved via gallery-dl as a fallback (yt-dlp failed).

imageCount

number

Number of images discovered (up to 10 previewed).

images

array

Preview array of up to 10 image objects, each with filename, extension, and url.

site

string

Hostname of the source URL (e.g. reddit.com).

Response — Playlist

When playlist=true, the response describes the full playlist rather than any individual video.

title

string

Playlist title as reported by yt-dlp.

isPlaylist

boolean

Always true.

videoCount

number

Total number of videos in the playlist.

videoTitles

string[]

Array of video titles, capped at the first 50 entries.

usingCookies

boolean

true when the server used a cookies file for the yt-dlp request.

Errors

Status	Meaning
`400`	Missing or invalid URL
`500`	yt-dlp / extractor failure
`504`	Metadata fetch timed out (30 s limit)

curl Example

Single video
Playlist

curl "https://yoink.example.com/api/metadata?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ"

curl "https://yoink.example.com/api/metadata?url=https%3A%2F%2Fwww.youtube.com%2Fplaylist%3Flist%3DPLbpi6ZahtOH6Ar_3GPy3workXXXXXXXX&playlist=true"

GET /api/download

Downloads a media file and streams the binary result to the client. The response carries a Content-Disposition: attachment header so browsers prompt a file save dialog.

GET /api/download?url={url}&format={format}&quality={quality}&...

The server enforces a per-client job limit of 3 concurrent downloads (configurable via MaxJobsPerClient). Exceeding this returns HTTP 429.

Query Parameters

url

string

required

URL of the media to download. Accepts any site supported by yt-dlp, as well as YouTube, TikTok, Twitter/X, and Instagram via dedicated extractors.

format

string

default:"video"

Output mode. One of video, audio, or photo. Passing photo for a YouTube URL downloads the highest-resolution thumbnail instead of the video.

quality

string

default:"1080p"

Target video resolution. One of 2160p, 1440p, 1080p, 720p, 480p, 360p. Ignored when format=audio.

container

string

default:"mp4"

Output video container. One of mp4, webm, mkv, mov. Ignored when format=audio.

audioFormat

string

default:"mp3"

Output audio codec / container when format=audio. One of mp3, m4a, opus, wav, flac.

audioBitrate

string

default:"320"

Audio encoding bitrate in kbps when format=audio. One of 64, 96, 128, 192, 256, 320.

filename

string

Optional output filename without extension. The server appends the appropriate extension automatically. Defaults to download.

progressId

string

Pre-generated UUID to use as the progress channel ID. Subscribe to GET /api/progress/{progressId} before starting the download to receive real-time status updates. If omitted, a random ID is generated internally.

clientId

string

Session identifier used for per-client job limiting. Pass a stable value (e.g. a browser fingerprint or user ID) to enforce the 3-concurrent-job limit correctly across requests.

twitterGifs

boolean

default:"true"

When true, Twitter/X videos that are detected as looping GIFs (via ffprobe) are automatically converted to .gif before streaming. Set to false to always receive the original video file.

playlist

boolean

default:"false"

Download the URL as a playlist and stream a ZIP archive. Deprecated — use POST /api/playlist/start for playlist downloads instead.

Response

On success, the server streams the binary media file directly. Headers include:

Header	Value
`Content-Type`	MIME type of the output (e.g. `video/mp4`, `audio/mpeg`)
`Content-Disposition`	`attachment; filename="<name>.<ext>"; filename*=UTF-8''<encoded>`
`Content-Length`	File size in bytes

On error, a JSON body is returned with an error string and the appropriate HTTP status code.

Errors

Status	Meaning
`400`	Invalid URL or bad parameters
`429`	Too many concurrent jobs for this client
`500`	Download or processing failure
`503`	Server is at job capacity

curl Examples

Download video (1080p MP4)
Download audio (MP3 320kbps)
Download with progress tracking
Download YouTube thumbnail

curl -L -o video.mp4 \
  "https://yoink.example.com/api/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&format=video&quality=1080p&container=mp4"

curl -L -o audio.mp3 \
  "https://yoink.example.com/api/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&format=audio&audioFormat=mp3&audioBitrate=320"

# Subscribe to progress first (in background)
PROGRESS_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl -N "https://yoink.example.com/api/progress/${PROGRESS_ID}" &

# Start download
curl -L -o video.mp4 \
  "https://yoink.example.com/api/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&progressId=${PROGRESS_ID}"

curl -L -o thumbnail.jpg \
  "https://yoink.example.com/api/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&format=photo"

Core

Endpoints

Download Media and Fetch Metadata from Any URL

GET /api/metadata

Query Parameters

Response — Single Video

Response — Playlist

Errors

curl Example

GET /api/download

Query Parameters

Response

Errors

curl Examples

Build docs developers (and LLMs) love

Core

Endpoints

Documentation Index

​GET /api/metadata

​Query Parameters

​Response — Single Video

​Response — Playlist

​Errors

​curl Example

​GET /api/download

​Query Parameters

​Response

​Errors

​curl Examples

Build docs developers (and LLMs) love

GET /api/metadata

Query Parameters

Response — Single Video

Response — Playlist

Errors

curl Example

GET /api/download

Query Parameters

Response

Errors

curl Examples