List YouTube Playlists API
The List YouTube Playlists API lets you list playlists for a connected YouTube channel. Call the endpoint with the connected channel's accountId, inspect the returned playlists array, and reuse a returned playlist id as platformSpecificData.playlistId when publishing a video.
List playlists for a connected YouTube channel
List playlists for a connected YouTube channel returns every playlist owned by the selected connected YouTube channel. Use the List YouTube Playlists API when you need to discover which playlists exist before publishing, scheduling, or organizing video content. The operation is a single GET request: GET {{API_BASE_URL}}/v1/youtube/accounts/{accountId}/playlists. Replace accountId in the path with the integration ID of the connected YouTube channel and send your access key in the x-access-key header. No additional query parameters or request body are part of this contract.
Authorization
Send the access key in the x-access-key header on every request. The header name is x-access-key and its value is the token shown as <token> in the request example titled List playlists request. The captured contract specifies this header; it does not define additional authorization behavior. Keep the token out of URLs, logs, and client-side bundles, and rotate it if it is exposed.
Path Parameters
The only path parameter is accountId, a required string that identifies the connected YouTube channel. It is the integration ID of the connected YouTube channel, not a playlist id and not a video id. Substitute the exact accountId value into the path segment between /accounts/ and /playlists. If you use the wrong accountId, you will list playlists for the wrong channel or receive an error response, so verify the accountId against your connected-account list before calling this endpoint.
Response Body
A successful call returns a JSON body with a required boolean success field and a required playlists array. Each entry in playlists is an object with required id, title, description, privacy, itemCount, and thumbnailUrl fields. The privacy field uses one of public, private, or unlisted. The itemCount field is an integer greater than or equal to zero. The thumbnailUrl field is a URI string or null, so your code must handle null instead of assuming every playlist has a thumbnail. See the field map table and the 200 success response example for the full contract.
200 application/json
Status 200 returns application/json with success set to true and playlists containing every playlist owned by the selected channel. As general client handling, treat the playlists array as the authoritative list returned for that call, including when it contains no entries, rather than substituting assumed entries. Validate success before reading playlists, and validate each playlist object before using its id, title, description, privacy, itemCount, or thumbnailUrl. Store the returned id values if you plan to reference a playlist later, because the id is the value you pass as playlistId when publishing.
404 application/json
Status 404 returns application/json with a required string error field. The captured contract defines only the shape of this body, so handle it generically: read the error string, surface it in logs, and do not attempt to parse playlists from the body. Common checks after a 404 are whether the accountId in the path matches a connected YouTube channel and whether the request path was typed exactly as /v1/youtube/accounts/{accountId}/playlists.
502 application/json
Status 502 returns application/json with a required string error field, using the same error shape as the 404 response. Because the contract does not define a specific cause for a 502, treat it as a failed request rather than as an empty playlist list. As general client guidance, log the status code and error string, avoid overwriting previously cached playlist data with an empty result, and consider retrying only after confirming the accountId and x-access-key header are unchanged and correct.
Worked example: using a returned playlist id when publishing a video
After a successful call, pick the playlist you want from the playlists array and read its id. When publishing a video, pass that value as platformSpecificData.playlistId so the video is associated with the chosen playlist. The worked example titled Use a returned playlist id as platformSpecificData.playlistId shows the shape of that handoff with a placeholder playlist id. Before publishing, double-check that the playlist id came from the same connected channel as the accountId you used to list playlists, and confirm the playlist privacy value matches your intent for the video.
Failure matrix and field map
Use the field map table to validate every field you read from the response, and use the failure matrix table to branch on status codes before parsing bodies. The most common failure checks are: success is true before reading playlists; playlists is an array; each playlist has all six required fields; privacy is one of public, private, or unlisted; itemCount is a non-negative integer; thumbnailUrl is a URI string or null; and error bodies contain only a string error field. If any check fails, log the raw status and body for diagnosis instead of silently substituting defaults.
| Field | Location | Type | Required | Constraints / notes |
|---|---|---|---|---|
| accountId | Path parameter | string | Yes | Integration ID of the connected YouTube channel. |
| x-access-key | Header | string (<token>) | Yes | Authorization header carrying the access key. |
| success | 200 response body | boolean | Yes | True on a successful playlist list. |
| playlists | 200 response body | array<object> | Yes | Every playlist owned by the selected connected YouTube channel. |
| playlists[].id | 200 response body | string | Yes | Playlist id; reuse as platformSpecificData.playlistId when publishing a video. |
| playlists[].title | 200 response body | string | Yes | Playlist title. |
| playlists[].description | 200 response body | string | Yes | Playlist description. |
| playlists[].privacy | 200 response body | string | Yes | Enum: public | private | unlisted. |
| playlists[].itemCount | 200 response body | integer | Yes | 0 <= value. |
| playlists[].thumbnailUrl | 200 response body | string | null | Yes | URI string or null; handle null explicitly. |
Exact captured contract; origin shown as {{API_BASE_URL}}.
| Status | Content type | Body shape | Client handling |
|---|---|---|---|
| 200 | application/json | { success: boolean, playlists: array<object> } | Validate success, then read playlists and each playlist field. |
| 404 | application/json | { error: string } | Read the error string; verify accountId and exact request path; do not parse playlists. |
| 502 | application/json | { error: string } | Read the error string; do not treat as an empty list; general guidance is to retry cautiously after re-checking accountId and x-access-key. |
Causes for 404 and 502 are not defined in the captured contract beyond the error string; no cause is invented here.
curl -X GET "{{API_BASE_URL}}/v1/youtube/accounts/string/playlists" \
-H "x-access-key: <token>"{
"success": true,
"playlists": [
{
"id": "string",
"title": "string",
"description": "string",
"privacy": "public",
"itemCount": 0,
"thumbnailUrl": "http://example.com"
}
]
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | Yes | the service integration ID of the connected YouTube channel. | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.playlists | array<object> | __2 | Yes | ||
| response#2 | response.playlists[] | object | __3 | |||
| response#2 | response.playlists[].id | string | __4 | Yes | ||
| response#2 | response.playlists[].title | string | __5 | Yes | ||
| response#2 | response.playlists[].description | string | __6 | Yes | ||
| response#2 | response.playlists[].privacy | string | __7 | Yes | kind: ; value: "public" | "private" | "unlisted" | |
| response#2 | response.playlists[].itemCount | integer | __8 | Yes | kind: ; value: 0 <= value | |
| response#2 | response.playlists[].thumbnailUrl | string | null | __9 | Yes | kind: ; value: uri | |
| response#2 | response.playlists[].thumbnailUrl[variant1] | string | __9_type:string | kind: ; value: uri | ||
| response#2 | response.playlists[].thumbnailUrl[variant2] | null | __9_type:null | kind: ; value: uri | ||
| response#3 | response | object | __0 | |||
| response#3 | response.error | string | __1 | Yes |