Skip to main content

YouTube Channel Settings

Read and change the settings of the YouTube channel connected to a profile: description, keywords, country, default language, the trailer shown to visitors who are not subscribed, translations, the banner, the sections (shelves) of the channel page and the watermark shown on the videos.

All endpoints take user (the profile username) and use the channel connected to that profile. Authentication: Authorization: Apikey your-api-key-here. They follow the common rules of the YouTube endpoints.

They spend the account's daily YouTube allowance (see Daily allowance). Uploads are never limited by it.

EndpointWhat it doesYouTube units
GET /api/uploadposts/youtube/channelRead the connected channel1 (cached 5 min)
GET /api/uploadposts/youtube/channel/lookupPublic data of any channel1 (cached 1 h)
PATCH /api/uploadposts/youtube/channelChange settings or translations51
POST /api/uploadposts/youtube/channel/bannerUpload and apply the banner101
GET /api/uploadposts/youtube/channel/sectionsList the sections1
POST /api/uploadposts/youtube/channel/sectionsCreate a section50
PATCH /api/uploadposts/youtube/channel/sections/{id}Edit or move a section51
DELETE /api/uploadposts/youtube/channel/sections/{id}Delete a section (confirm)51
POST /api/uploadposts/youtube/channel/watermarkSet the watermark (confirm)50
DELETE /api/uploadposts/youtube/channel/watermarkRemove the watermark (confirm)50

Invalid input (texts too long, values that are not text, wrong ids, images of the wrong type or size) is refused with 400 (413 for a file that is too large) before anything is sent to YouTube, so it costs nothing. Your remaining allowance is checked before an image is read or downloaded.

Changes to the same channel run one at a time (settings, banner and sections): a second change sent while one is in progress answers 409 youtube_channel_busy without changing or charging anything. Retry it a moment later.

Read the channel​

GET /api/uploadposts/youtube/channel?user=my-profile

Returns YouTube's channel resource with snippet, brandingSettings, status, statistics, localizations, topicDetails and contentDetails. The answer is cached for 5 minutes ("cached": true). After any change made through these endpoints the cache is dropped and, for about a minute, every read goes to YouTube (YouTube itself may still show the old values for a few seconds).

{
"success": true,
"cached": false,
"channel": {
"id": "UCxxxxxxxxxxxxxxxxxxxxxx",
"snippet": {"title": "My channel", "customUrl": "@mychannel", "country": "ES"},
"brandingSettings": {
"channel": {"title": "My channel", "description": "Weekly videos", "keywords": "vlog \"video editing\"",
"country": "ES", "defaultLanguage": "es", "unsubscribedTrailer": "dQw4w9WgXcQ"},
"image": {"bannerExternalUrl": "https://yt3.googleusercontent.com/..."}
},
"localizations": {"en": {"title": "My channel", "description": "Weekly videos"}},
"statistics": {"viewCount": "12000", "subscriberCount": "340", "videoCount": "52"}
}
}

Look up another channel​

GET /api/uploadposts/youtube/channel/lookup?user=my-profile&for_handle=@GoogleDevelopers

Exactly one of:

NameDescription
idsUp to 50 channel IDs (UC...), comma separated. The answer adds not_found.
for_handleA handle, with or without @.
for_usernameA legacy YouTube username.

For other channels only public data comes back; when you look up the connected channel itself, YouTube also returns the fields only its owner sees. Answers are cached for one hour, separately for each connected channel.

Change the channel settings​

PATCH /api/uploadposts/youtube/channel
Content-Type: application/json
FieldDescription
userProfile username. Required.
descriptionText, up to 1,000 characters, without < or >.
keywordsA string (space separated; multi-word keywords in double quotes) or a list (["vlog", "video editing"]). Up to 500 characters in total.
countryISO 3166-1 code, e.g. ES.
default_languageBCP-47 code of the channel's title and description, e.g. es, en-US.
unsubscribed_trailerID of a public or unlisted video of the channel, shown to visitors who are not subscribed.
tracking_analytics_account_idGoogle Analytics ID used to measure the channel page.
localizationsTranslations of the channel name and description: {"en": {"title": "...", "description": "..."}}. A language set to null is removed.
localizations_removeList of languages to remove, e.g. ["fr"].

Every text field must be a string (keywords also accepts a list of strings): any other type is refused with 400 invalid_field and the field it refers to.

Rules that protect your channel:

  • Only what you send changes. YouTube erases every setting that is not resent, so Upload-Post reads the channel first and sends back everything you did not touch (banner included).
  • Empty means "no change". "" leaves a field as it is. To clear a field send null (for example "unsubscribed_trailer": null).
  • One kind of change per call. YouTube updates the settings and the translations separately: send them in two requests. Translations need default_language to be set on the channel.
  • Nothing lost in silence. After the update Upload-Post compares YouTube's answer with the channel as it was: if a setting you did not touch (description, keywords, country, default language, trailer, Analytics ID, banner or a translation) is missing from the answer, the response carries warnings. Check the channel and set it again if it was cleared.
  • Default language. YouTube may set the channel's default language by itself (for example when the first settings or translations are saved) and "default_language": null does not always remove it: if it stays, the response carries warnings. Change it in YouTube Studio if needed.
  • The channel name cannot be changed by API (YouTube rejects it): change it in YouTube Studio. The same goes for the channel's made-for-kids setting.
curl -X PATCH https://api.upload-post.com/api/uploadposts/youtube/channel \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "description": "New videos every Monday", "keywords": ["vlog", "video editing"]}'
{
"success": true,
"updated_part": "brandingSettings",
"updated_fields": ["description", "keywords"],
"channel": {"id": "UCxxxxxxxxxxxxxxxxxxxxxx", "brandingSettings": {"channel": {"description": "New videos every Monday"}}}
}

Translations​

YouTube stores translations under its own codes and may turn fr into fr_FR (and add one for the default language). Codes are accepted with - or _ (pt-BR, fr_FR) and are matched against the channel's real translations: exactly, or by base language when only one translation has it (fr matches fr_FR). A code that matches several (pt with pt_BR and pt_PT) answers 400 youtube_localization_ambiguous: send the exact code.

curl -X PATCH https://api.upload-post.com/api/uploadposts/youtube/channel \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "localizations_remove": ["fr"]}'
{
"success": true,
"updated_part": "localizations",
"updated_fields": ["localizations"],
"localizations_removed": ["fr_FR"],
"channel": {"id": "UCxxxxxxxxxxxxxxxxxxxxxx", "localizations": {"en_US": {"title": "My channel", "description": "Weekly videos"}}}
}

localizations_removed lists the real codes that were removed. If nothing matches a removal and there is nothing else to change, the call answers 404 youtube_localization_not_found with missing and available (the channel's codes) after a 1-unit read, without the update. A removal that matches nothing next to other changes is skipped with a warnings entry, and warnings also says so if YouTube's answer still shows a translation you removed.

POST /api/uploadposts/youtube/channel/banner

Send the image as the multipart file image, or a public image_url. PNG or JPEG, up to 6 MB, 16:9, at least 2048×1152 (2560×1440 recommended). Upload-Post uploads it and makes it the channel banner, keeping every other setting (warnings if one of them is missing from YouTube's answer). An image_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 image or image_url, not both (400 ambiguous_source).

curl -X POST https://api.upload-post.com/api/uploadposts/youtube/channel/banner \
-H 'Authorization: Apikey your-api-key-here' \
-F 'user=my-profile' -F '[email protected]'
{"success": true, "banner_url": "https://yt3.googleusercontent.com/...", "uploaded": true}

If the image was uploaded but YouTube refused to apply it, the error is youtube_banner_not_applied and carries banner_url. Send {"user": "...", "banner_url": "<that url>"} to the same endpoint to apply it without uploading again. If YouTube did not answer the second step in time, the error is 502 youtube_write_outcome_unknown, also with banner_url: the banner may already be applied, so check it with GET /channel and send banner_url only if it did not change.

Sections​

GET  /api/uploadposts/youtube/channel/sections?user=my-profile
POST /api/uploadposts/youtube/channel/sections
PATCH /api/uploadposts/youtube/channel/sections/{section_id}
DELETE /api/uploadposts/youtube/channel/sections/{section_id}

A channel has up to 10 sections. They only show on the channel page when its browse view is enabled.

FieldDescription
typeallPlaylists, completedEvents, liveEvents, multipleChannels, multiplePlaylists, popularUploads, recentUploads, singlePlaylist, subscriptions or upcomingEvents. Required to create.
titleRequired for multiplePlaylists and multipleChannels (up to 100 characters); YouTube ignores it for the other types.
playlistsPlaylist IDs: exactly one for singlePlaylist, one or more for multiplePlaylists.
channelsChannel IDs for multipleChannels (not your own channel).
position0 to 9. Omit it to add the section last. On PATCH, moving a section reorders the others.

PATCH changes only what you send. Changing type needs whatever the new type requires. DELETE needs "confirm": true and cannot be undone. Before a PATCH or DELETE the section is read (1 unit): a section of another channel answers 404 youtube_not_found without spending the write.

curl -X POST https://api.upload-post.com/api/uploadposts/youtube/channel/sections \
-H 'Authorization: Apikey your-api-key-here' -H 'Content-Type: application/json' \
-d '{"user": "my-profile", "type": "multiplePlaylists", "title": "Best of", "playlists": ["PLxxxx", "PLyyyy"], "position": 0}'

Watermark​

POST   /api/uploadposts/youtube/channel/watermark
DELETE /api/uploadposts/youtube/channel/watermark

The watermark (branding image) shows in the top right corner of the channel's videos.

FieldDescription
image / image_urlPNG or JPEG, up to 10 MB. A square image of 150×150 is what YouTube recommends. Same URL rules as the banner.
confirmMust be true: the new watermark replaces the current one (YouTube keeps no copy).
timing_typeoffsetFromStart (default) or offsetFromEnd.
offset_msWhen it appears, in milliseconds from the start or the end. With offsetFromEnd, 1000 or more.
duration_msHow long it shows (1000 or more). With offsetFromEnd, not longer than offset_ms. Omit it to keep it until the end.
target_channel_idChannel the watermark links to. Default: this channel.

POST and DELETE both need "confirm": true (400 confirmation_required otherwise).

Errors​

error_codeMeaning
nothing_to_updateNo field to change (empty values mean "no change").
youtube_channel_one_partSettings and translations in the same call: split them.
youtube_channel_title_read_onlyThe channel name cannot be changed by API.
youtube_default_language_requiredSet default_language before adding translations.
invalid_<field>A field is not valid; the message says why.
invalid_fieldA field is not text (the body names the field).
invalid_jsonThe body is not a valid JSON object.
invalid_localizations, youtube_localization_ambiguousA translation code is not valid, or matches several translations.
youtube_localization_not_found (404)No translation matches the codes to remove; the body has missing and available.
missing_file, ambiguous_source, invalid_url, download_failed, invalid_image_format, image_too_small, invalid_image_aspect_ratioThe image was refused before calling YouTube.
file_too_large (413)The image is larger than its maximum (banner 6 MB, watermark 10 MB).
youtube_banner_not_appliedThe banner was uploaded but not applied: retry with banner_url.
youtube_channel_busy (409)Another change of this channel is in progress; nothing was changed or charged.
youtube_write_outcome_unknown (502)YouTube did not confirm a change in time: it may or may not be applied. Check with GET /channel before sending it again.
youtube_banner_album_fullThe channel's Channel Art album is full.
youtube_sections_limitThe channel already has 10 sections.
youtube_section_not_found, youtube_section_not_editableThe section does not exist or YouTube does not allow changing it.
confirmation_requiredSend "confirm": true.
youtube_daily_budget_exhausted, youtube_quota_exhaustedDaily allowance used up; see retry_after and resets_at.
youtube_insufficient_scope, youtube_reauth_requiredReconnect the YouTube account.
youtube_feature_disabled (503)YouTube management features are temporarily off on Upload-Post. Uploads keep working.