YouTube
YouTube playlist and channel feeds: source preview, Data API key test, cookies, and yt-dlp updates. Global settings live under Settings.
POST /youtube/preview
Section titled “POST /youtube/preview”Preview a YouTube source
Resolves a playlist, channel or handle URL and returns its identity plus podcast directory matches that may offer the same show as an RSS feed. Returns enabled false with no lookup when YouTube feeds are disabled.
Request body (application/json, required)
Section titled “Request body (application/json, required)”url(string, required)
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Source preview | object |
| 400 | Not a YouTube playlist or channel URL | |
| 404 | Source not found or private | |
| 502 | The lookup failed upstream |
200 response body
Section titled “200 response body”enabled(boolean)source(object or null)source.kind(string, one ofplaylist,channel)source.id(string)source.title(string)source.description(string)source.author(string): Channel title; for a playlist, the owning channel. Seeds itunes:author when the feed is added.source.artworkUrl(string or null)source.videoCount(integer or null)source.alreadyAdded(string or null): Slug of the existing feed for this source, if any.rssMatches(array of object)rssMatches[].title(string)rssMatches[].feedUrl(string)rssMatches[].artworkUrl(string)
GET /youtube/search
Section titled “GET /youtube/search”Search YouTube playlists and channels by name
Returns ranked playlist and channel candidates for a show name. Playlists the channel owner marked as a podcast rank first. Uses the Data API when a key is set and yt-dlp otherwise. Results are cached for 10 minutes. Returns enabled false with no lookup when YouTube feeds are disabled.
Parameters
Section titled “Parameters”q(query, string, required): Show name to search for.
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Ranked candidates | object |
| 400 | Missing search query | |
| 502 | The search failed upstream |
200 response body
Section titled “200 response body”enabled(boolean)results(array of object)results[].kind(string, one ofplaylist,channel)results[].id(string)results[].title(string)results[].channelTitle(string)results[].videoCount(integer or null)results[].podcast(boolean or null): True when YouTube marks the playlist as a podcast show. Null for channels and unknown status.results[].artworkUrl(string or null)results[].url(string): Public YouTube URL to paste into the Add feed lookup, for example https://www.youtube.com/playlist?list=PL…
POST /youtube/test-key
Section titled “POST /youtube/test-key”Test a YouTube Data API key
Tests the supplied key, or the stored key when apiKey is omitted, against a public channel.
Request body (application/json)
Section titled “Request body (application/json)”apiKey(string)
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | The key works | object |
| 400 | No key available or YouTube rejected it |
200 response body
Section titled “200 response body”ok(boolean)channelTitle(string or null)
POST /youtube/cookies
Section titled “POST /youtube/cookies”Save YouTube cookies
Stores a Netscape-format cookies file used by yt-dlp. The content is never returned.
Request body (application/json, required)
Section titled “Request body (application/json, required)”cookies(string, required)
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Cookies status | YoutubeCookiesStatus |
| 400 | The text is not a valid cookies file |
DELETE /youtube/cookies
Section titled “DELETE /youtube/cookies”Remove YouTube cookies
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Cookies status after removal | YoutubeCookiesStatus |
POST /youtube/ytdlp/update
Section titled “POST /youtube/ytdlp/update”Update yt-dlp now
Downloads the latest yt-dlp into the runtime copy. Limited to 6 requests per hour.
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Update result | object |
| 503 | yt-dlp is not installed |
200 response body
Section titled “200 response body”updated(boolean)version(string or null)error(string or null)