Skip to main content

YouTube Playlists

Manage the playlists of the YouTube channel connected to a profile after you publish: create and edit playlists (title, description, privacy, podcast status, translations), add videos that are already on YouTube, reorder them, add a note to each one, remove them, and set the playlist image.

To add a video to a playlist while uploading it, keep using playlist_id in Upload video; nothing changes there.

All endpoints take the profile in user (query string, JSON body or form field) and use your daily allowance for YouTube management features. Every write first checks that the playlist belongs to the connected channel (1 unit), so a wrong ID never costs a full write. They follow the common rules of the YouTube endpoints.

EndpointYouTube cost (units)
GET /api/uploadposts/youtube/playlists1
POST /api/uploadposts/youtube/playlists50
PATCH /api/uploadposts/youtube/playlists/{playlist_id}51
DELETE /api/uploadposts/youtube/playlists/{playlist_id}51
GET /api/uploadposts/youtube/playlists/{playlist_id}/items1
POST /api/uploadposts/youtube/playlists/{playlist_id}/items52
PATCH /api/uploadposts/youtube/playlists/{playlist_id}/items/{item_id}52
DELETE /api/uploadposts/youtube/playlists/{playlist_id}/items/{item_id}52
GET /api/uploadposts/youtube/playlists/{playlist_id}/image1
POST / PUT /api/uploadposts/youtube/playlists/{playlist_id}/image51 / 52
DELETE /api/uploadposts/youtube/playlists/{playlist_id}/image52

Headers​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

List playlists​

GET /api/uploadposts/youtube/playlists

Without filters it returns the connected channel's own playlists, one page per call.

NameTypeRequiredDescription
userStringYesProfile username with a YouTube channel connected.
idsStringNoUp to 50 playlist IDs, comma separated (any channel's public playlists).
channel_idStringNoPublic playlists of another channel (UC…). Not with ids.
partsStringNoComma-separated subset of snippet, status, contentDetails, localizations, player. Default: all but player.
hlStringNoLanguage for snippet.localized (e.g. es).
max_resultsIntegerNo1-50 (YouTube's default is 5). Not with ids.
page_tokenStringNoThe next_page_token of the previous page.
curl -G https://api.upload-post.com/api/uploadposts/youtube/playlists \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'max_results=50'
{
"success": true,
"items": [
{
"id": "PLxxxxxxxxxxxxxxxx",
"snippet": {"channelId": "UCxxxxxxxxxxxxxxxxxxxxxx", "title": "Tutorials", "description": "", "defaultLanguage": "en"},
"status": {"privacyStatus": "public", "podcastStatus": "disabled"},
"contentDetails": {"itemCount": 12},
"localizations": {"es": {"title": "Tutoriales"}}
}
],
"next_page_token": "CAUQAA",
"page_info": {"totalResults": 7, "resultsPerPage": 5}
}

With ids, the answer also has not_found: the IDs YouTube did not return.

Create a playlist​

POST /api/uploadposts/youtube/playlists
NameTypeRequiredDescription
userStringYesProfile username.
titleStringYesUp to 150 characters.
descriptionStringNoUp to 5,000 characters.
privacy_statusStringNopublic, unlisted or private. If omitted, YouTube applies its default.
default_languageStringNoLanguage of the title and description (BCP-47, e.g. en). Required with localizations.
localizationsObjectNoTranslations: {"es": {"title": "…", "description": "…"}}.

podcast_status cannot be set on creation (YouTube only accepts it when editing): create the playlist, add its image, then edit it.

curl -X POST https://api.upload-post.com/api/uploadposts/youtube/playlists \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "title": "Tutorials", "privacy_status": "unlisted", "default_language": "en", "localizations": {"es": {"title": "Tutoriales"}}}'

Answer 201 with {"success": true, "playlist": {…}} (YouTube's playlist resource).

Edit a playlist​

PATCH /api/uploadposts/youtube/playlists/{playlist_id}

Send only what you want to change: everything else (title, description, privacy, other translations) is kept. An empty string ("") means no change: "title": "" alone answers 400 nothing_to_update. "description": null clears the description; "title": null is refused (400 invalid_title: a playlist always has a title). Text fields must be strings.

NameTypeDescription
title, description, privacy_status, default_language, localizationsAs in creation. New translations are merged with the existing ones.
podcast_statusStringenabled or disabled. enabled marks the playlist as a podcast and needs a playlist image.
localizations_removeArrayLanguages to remove, e.g. ["fr"].

Language codes. YouTube may store a translation under a regional code (fr_FR for fr). Codes are accepted with - or _ (pt-BR, fr_FR) and are matched against the playlist's real translations: exactly, or by base language when only one translation has it (fr matches fr_FR). If a code matches several (pt with pt_BR and pt_PT), the call answers 400 youtube_localization_ambiguous: send the exact code. If nothing matches a code in localizations_remove and there is nothing else to change, the call answers 404 youtube_localization_not_found with missing and available (the playlist's codes) after a 1-unit read, without the update. When the call also changes something else, the unmatched code is skipped with a warnings entry; warnings also says so if YouTube's answer still shows a translation you removed.

curl -X PATCH https://api.upload-post.com/api/uploadposts/youtube/playlists/PLxxxxxxxxxxxxxxxx \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "privacy_status": "public", "podcast_status": "enabled"}'

The uploads playlist and other playlists YouTube manages itself (likes, watch later, mixes) cannot be changed: 400 youtube_playlist_operation_unsupported.

Delete a playlist​

DELETE /api/uploadposts/youtube/playlists/{playlist_id}?user=my-profile&confirm=true

Deleting cannot be undone, so confirm=true is required (400 confirmation_required otherwise). The videos are not deleted.

Playlist videos​

List​

GET /api/uploadposts/youtube/playlists/{playlist_id}/items
NameTypeDescription
userStringProfile username.
video_idStringOnly the items of this video.
partsStringSubset of snippet, contentDetails, status (default: all).
max_results, page_tokenOne page per call (1-50 items).

Each item has its id (the item ID, used below), snippet.position (0 = first) and contentDetails.note.

Add a video​

POST /api/uploadposts/youtube/playlists/{playlist_id}/items
NameTypeRequiredDescription
video_idStringYesAny video already on YouTube (yours or a public one).
positionIntegerNoZero-based place in the playlist (0 = first). Only for playlists sorted manually; without it the video goes to the end.
noteStringNoNote shown for this video in the playlist, up to 280 characters.
curl -X POST https://api.upload-post.com/api/uploadposts/youtube/playlists/PLxxxxxxxxxxxxxxxx/items \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "video_id": "dQw4w9WgXcQ", "position": 0}'

Answer 201 with {"success": true, "item": {…}}.

Reorder or change the note​

PATCH /api/uploadposts/youtube/playlists/{playlist_id}/items/{item_id}

Send position (new zero-based place) and/or note ("" clears it). The other field is kept. If the playlist is not sorted manually YouTube refuses a position: 400 youtube_manual_sort_required (set the playlist's ordering to Manual in YouTube Studio).

Remove a video​

DELETE /api/uploadposts/youtube/playlists/{playlist_id}/items/{item_id}?user=my-profile&confirm=true

Removes the video from the playlist (the video itself stays). Requires confirm=true.

A playlist holds up to 5,000 videos: adding to a full playlist answers 400 youtube_playlist_full after the 1-unit ownership read, without the insert.

Playlist image​

YouTube's playlist image (required for podcasts): JPEG or PNG, square (1:1), up to 50 MB.

MethodDescription
GET …/{playlist_id}/imageCurrent image: {"success": true, "image": {…} or null, "items": […], "next_page_token": null, "page_info": null}.
POST …/{playlist_id}/imageAdd the image. multipart/form-data with image (file), or image_url (public URL).
PUT …/{playlist_id}/imageReplace the current image (same fields, plus confirm=true: the current image is overwritten).
DELETE …/{playlist_id}/image?confirm=trueRemove the image.
curl -X POST https://api.upload-post.com/api/uploadposts/youtube/playlists/PLxxxxxxxxxxxxxxxx/image \
-H 'Authorization: Apikey your-api-key-here' \
-F 'user=my-profile' \
-F '[email protected]'

The image is checked before anything is sent to YouTube: invalid_image_format, invalid_image_aspect_ratio, file_too_large (413). An *_url must be a public http(s) URL of up to 2,048 characters, and the whole download has a time limit: a URL that is private, too slow or answers an error is refused with 400 download_failed (invalid_url for local or non-public addresses). Send either the file or the URL, not both (400 ambiguous_source).

When YouTube does not confirm a change​

If YouTube does not answer in time after a change was sent, the answer is 502 youtube_write_outcome_unknown: the change may or may not have been applied. Upload-Post never retries it on its own; list the playlist (or its videos) before trying again, so a video is not added twice.

Error responses​

Same shape as every YouTube endpoint (success: false, error, error_code, and youtube_status/youtube_reason when they come from YouTube); see video details for the common ones. Specific to playlists:

  • 400 — invalid_title, invalid_description, invalid_json, invalid_privacy_status, invalid_podcast_status, podcast_status_on_create, invalid_language, invalid_localizations, youtube_localization_ambiguous, youtube_default_language_required, invalid_playlist_id, invalid_item_id, invalid_video_id, invalid_position, invalid_note, nothing_to_update, confirmation_required, youtube_playlist_operation_unsupported, youtube_manual_sort_required, youtube_video_in_another_series, youtube_playlist_limit_reached, youtube_playlist_full (5,000 videos), invalid_image_format, invalid_image_aspect_ratio, missing_file, ambiguous_source, invalid_url, download_failed.
  • 403 — youtube_playlist_forbidden, youtube_playlist_full (YouTube itself refused: the playlist has its maximum number of videos), youtube_playlist_items_not_accessible.
  • 404 — youtube_playlist_not_found (not on the connected channel), youtube_playlist_item_not_found, youtube_video_not_found, youtube_playlist_image_not_found, youtube_localization_not_found (with missing and available).
  • 413 — file_too_large.
  • 502 — youtube_write_outcome_unknown (see above).
  • 503 — youtube_feature_disabled: YouTube management features are temporarily off on Upload-Post. Uploads keep working.