Youtube Playlists API
Manages YouTube playlists including creating, updating, deleting, and listing playlists associated with a channel or the authenticated user.
OpenAPI Specification
openapi: 3.1.0
info:
title: YouTube Data API v3
description: >-
The YouTube Data API v3 provides access to YouTube data including videos, channels,
playlists, comments, subscriptions, captions, and other YouTube resources. It allows
applications to search for content and manage YouTube accounts programmatically.
version: v3
contact:
name: YouTube API Support
url: https://developers.google.com/youtube/v3/support
termsOfService: https://developers.google.com/youtube/terms/api-services-terms-of-service
servers:
- url: https://www.googleapis.com/youtube/v3
description: YouTube Data API v3 base server
security:
- oauth2:
- https://www.googleapis.com/auth/youtube
- apiKey: []
tags:
- name: Captions
description: Operations related to YouTube video caption tracks
- name: Channels
description: Operations related to YouTube channel resources
- name: Comments
description: Operations related to individual YouTube comments
- name: CommentThreads
description: Operations related to YouTube comment threads
- name: I18n
description: Operations related to internationalization resources
- name: PlaylistItems
description: Operations related to items within YouTube playlists
- name: Playlists
description: Operations related to YouTube playlist resources
- name: Search
description: Operations for searching YouTube content
- name: Subscriptions
description: Operations related to YouTube channel subscriptions
- name: VideoCategories
description: Operations related to YouTube video categories
- name: Videos
description: Operations related to YouTube video resources
paths:
/videos:
get:
operationId: youtube.videos.list
summary: Youtube List Videos
description: >-
Returns a list of videos that match the API request parameters. Requires the part
parameter to specify the video resource properties to include in the response.
tags:
- Videos
parameters:
- $ref: '#/components/parameters/part'
- name: id
in: query
description: >-
Comma-separated list of YouTube video IDs for the resources being retrieved.
schema:
type: string
example: abc123def456
- name: chart
in: query
description: >-
Identifies the chart that the API returns chart data for. Acceptable values are
mostPopular and videoCategoryId.
schema:
type: string
enum:
- mostPopular
example: mostPopular
- name: myRating
in: query
description: >-
Set this parameter to like or dislike to instruct the API to return only videos
liked or disliked by the authenticated user.
schema:
type: string
enum:
- like
- dislike
example: like
- $ref: '#/components/parameters/maxResults'
- $ref: '#/components/parameters/pageToken'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
responses:
'200':
description: Successful response containing a list of video resources.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
examples:
YoutubeVideosList200Example:
summary: Default youtube.videos.list 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
prevPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
pageInfo:
totalResults: 42
resultsPerPage: 10
items:
- kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
localizations: example_value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: youtube.videos.insert
summary: Youtube Upload or Insert a Video
description: >-
Uploads a video to YouTube and optionally sets the video's metadata. This method
supports media upload and requires the part parameter to specify the video resource
properties to set.
tags:
- Videos
parameters:
- $ref: '#/components/parameters/part'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
requestBody:
description: The video resource to insert.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
examples:
YoutubeVideosInsertRequestExample:
summary: Default youtube.videos.insert request
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
categoryId: '500123'
liveBroadcastContent: live
defaultLanguage: en
localized:
title: Example Title
description: A sample description for this resource.
contentDetails:
duration: example_value
dimension: example_value
definition: hd
caption: 'false'
licensedContent: true
contentRating: example_value
status:
uploadStatus: deleted
privacyStatus: private
license: creativeCommon
embeddable: true
publicStatsViewable: true
madeForKids: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
statistics:
viewCount: 42
likeCount: 42
dislikeCount: 42
favoriteCount: 42
commentCount: 42
player:
embedHtml: example_value
embedHeight: 42.5
embedWidth: 42.5
localizations: example_value
responses:
'200':
description: Successful response containing the inserted video resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
examples:
YoutubeVideosInsert200Example:
summary: Default youtube.videos.insert 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
categoryId: '500123'
liveBroadcastContent: live
defaultLanguage: en
localized:
title: Example Title
description: A sample description for this resource.
contentDetails:
duration: example_value
dimension: example_value
definition: hd
caption: 'false'
licensedContent: true
contentRating: example_value
status:
uploadStatus: deleted
privacyStatus: private
license: creativeCommon
embeddable: true
publicStatsViewable: true
madeForKids: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
statistics:
viewCount: 42
likeCount: 42
dislikeCount: 42
favoriteCount: 42
commentCount: 42
player:
embedHtml: example_value
embedHeight: 42.5
embedWidth: 42.5
localizations: example_value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: youtube.videos.update
summary: Youtube Update Video Metadata
description: >-
Updates a video's metadata. This method supports patch semantics and requires the
part parameter to specify the video resource properties to update.
tags:
- Videos
parameters:
- $ref: '#/components/parameters/part'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
requestBody:
description: The video resource with updated properties.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
examples:
YoutubeVideosUpdateRequestExample:
summary: Default youtube.videos.update request
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
categoryId: '500123'
liveBroadcastContent: live
defaultLanguage: en
localized:
title: Example Title
description: A sample description for this resource.
contentDetails:
duration: example_value
dimension: example_value
definition: hd
caption: 'false'
licensedContent: true
contentRating: example_value
status:
uploadStatus: deleted
privacyStatus: private
license: creativeCommon
embeddable: true
publicStatsViewable: true
madeForKids: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
statistics:
viewCount: 42
likeCount: 42
dislikeCount: 42
favoriteCount: 42
commentCount: 42
player:
embedHtml: example_value
embedHeight: 42.5
embedWidth: 42.5
localizations: example_value
responses:
'200':
description: Successful response containing the updated video resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
examples:
YoutubeVideosUpdate200Example:
summary: Default youtube.videos.update 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
categoryId: '500123'
liveBroadcastContent: live
defaultLanguage: en
localized:
title: Example Title
description: A sample description for this resource.
contentDetails:
duration: example_value
dimension: example_value
definition: hd
caption: 'false'
licensedContent: true
contentRating: example_value
status:
uploadStatus: deleted
privacyStatus: private
license: creativeCommon
embeddable: true
publicStatsViewable: true
madeForKids: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
statistics:
viewCount: 42
likeCount: 42
dislikeCount: 42
favoriteCount: 42
commentCount: 42
player:
embedHtml: example_value
embedHeight: 42.5
embedWidth: 42.5
localizations: example_value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: youtube.videos.delete
summary: Youtube Delete a Video
description: >-
Deletes a YouTube video. The authenticated user must own the video or be authorized
to delete it.
tags:
- Videos
parameters:
- name: id
in: query
required: true
description: The ID of the video to delete.
schema:
type: string
example: abc123def456
- $ref: '#/components/parameters/key'
responses:
'204':
description: The video was successfully deleted.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/videos/rate:
post:
operationId: youtube.videos.rate
summary: Youtube Rate a Video
description: >-
Adds a like or dislike rating to a video or removes a rating from a video. The
authenticated user must be authorized to rate videos.
tags:
- Videos
parameters:
- name: id
in: query
required: true
description: The ID of the video to rate.
schema:
type: string
example: abc123def456
- name: rating
in: query
required: true
description: >-
The rating to record. Valid values are like, dislike, and none.
schema:
type: string
enum:
- like
- dislike
- none
example: like
- $ref: '#/components/parameters/key'
responses:
'204':
description: The rating was successfully applied or removed.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/channels:
get:
operationId: youtube.channels.list
summary: Youtube List Channels
description: >-
Returns a collection of zero or more channel resources that match the request
criteria. Use the part parameter to specify the channel resource properties to include.
tags:
- Channels
parameters:
- $ref: '#/components/parameters/part'
- name: id
in: query
description: >-
Comma-separated list of YouTube channel IDs for the resources being retrieved.
schema:
type: string
example: abc123def456
- name: mine
in: query
description: >-
Set this parameter to true to instruct the API to return channels owned by the
authenticated user.
schema:
type: boolean
example: true
- name: forUsername
in: query
description: >-
A YouTube username identifying a channel. The API returns the channel associated
with that username.
schema:
type: string
example: example_value
- $ref: '#/components/parameters/maxResults'
- $ref: '#/components/parameters/pageToken'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
responses:
'200':
description: Successful response containing a list of channel resources.
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelListResponse'
examples:
YoutubeChannelsList200Example:
summary: Default youtube.channels.list 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
prevPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
pageInfo:
totalResults: 42
resultsPerPage: 10
items:
- kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
contentDetails:
relatedPlaylists: {}
brandingSettings:
channel: {}
image: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: youtube.channels.update
summary: Youtube Update Channel Metadata
description: >-
Updates a channel's metadata. The authenticated user must own the channel being
updated. Use the part parameter to specify the channel properties to update.
tags:
- Channels
parameters:
- $ref: '#/components/parameters/part'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
requestBody:
description: The channel resource with updated properties.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Channel'
examples:
YoutubeChannelsUpdateRequestExample:
summary: Default youtube.channels.update request
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
title: Example Title
description: A sample description for this resource.
customUrl: https://www.example.com
publishedAt: '2026-01-15T10:30:00Z'
thumbnails: example_value
country: 42
localized:
title: Example Title
description: A sample description for this resource.
statistics:
viewCount: 42
subscriberCount: 42
hiddenSubscriberCount: 42
videoCount: 42
contentDetails:
relatedPlaylists:
uploads: example_value
likes: example_value
brandingSettings:
channel:
title: Example Title
description: A sample description for this resource.
keywords: example_value
defaultLanguage: en
image:
bannerExternalUrl: https://www.example.com
responses:
'200':
description: Successful response containing the updated channel resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Channel'
examples:
YoutubeChannelsUpdate200Example:
summary: Default youtube.channels.update 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
title: Example Title
description: A sample description for this resource.
customUrl: https://www.example.com
publishedAt: '2026-01-15T10:30:00Z'
thumbnails: example_value
country: 42
localized:
title: Example Title
description: A sample description for this resource.
statistics:
viewCount: 42
subscriberCount: 42
hiddenSubscriberCount: 42
videoCount: 42
contentDetails:
relatedPlaylists:
uploads: example_value
likes: example_value
brandingSettings:
channel:
title: Example Title
description: A sample description for this resource.
keywords: example_value
defaultLanguage: en
image:
bannerExternalUrl: https://www.example.com
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/playlists:
get:
operationId: youtube.playlists.list
summary: Youtube List Playlists
description: >-
Returns a collection of playlists that match the API request parameters. You can
retrieve playlists by ID, by channel, or for the authenticated user.
tags:
- Playlists
parameters:
- $ref: '#/components/parameters/part'
- name: id
in: query
description: Comma-separated list of YouTube playlist IDs for the resources being retrieved.
schema:
type: string
example: abc123def456
- name: channelId
in: query
description: >-
Indicates that the API response should only contain resources created by the channel.
schema:
type: string
example: '500123'
- name: mine
in: query
description: >-
Set this parameter to true to instruct the API to return playlists owned by the
authenticated user.
schema:
type: boolean
example: true
- $ref: '#/components/parameters/maxResults'
- $ref: '#/components/parameters/pageToken'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
responses:
'200':
description: Successful response containing a list of playlist resources.
content:
application/json:
schema:
$ref: '#/components/schemas/PlaylistListResponse'
examples:
YoutubePlaylistsList200Example:
summary: Default youtube.playlists.list 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
prevPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
pageInfo:
totalResults: 42
resultsPerPage: 10
items:
- kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags: {}
defaultLanguage: en
status:
privacyStatus: private
contentDetails:
itemCount: 42
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: youtube.playlists.insert
summary: Youtube Create a Playlist
description: >-
Creates a playlist on behalf of the authenticated user. The user must be authorized
to create playlists.
tags:
- Playlists
parameters:
- $ref: '#/components/parameters/part'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
requestBody:
description: The playlist resource to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Playlist'
examples:
YoutubePlaylistsInsertRequestExample:
summary: Default youtube.playlists.insert request
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
defaultLanguage: en
status:
privacyStatus: private
contentDetails:
itemCount: 42
responses:
'200':
description: Successful response containing the newly created playlist resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Playlist'
examples:
YoutubePlaylistsInsert200Example:
summary: Default youtube.playlists.insert 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
defaultLanguage: en
status:
privacyStatus: private
contentDetails:
itemCount: 42
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: youtube.playlists.update
summary: Youtube Update a Playlist
description: >-
Modifies a playlist. The authenticated user must own the playlist being updated.
Use the part parameter to specify the properties being updated.
tags:
- Playlists
parameters:
- $ref: '#/components/parameters/part'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/key'
requestBody:
description: The playlist resource with updated properties.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Playlist'
examples:
YoutubePlaylistsUpdateRequestExample:
summary: Default youtube.playlists.update request
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
- example_value
defaultLanguage: en
status:
privacyStatus: private
contentDetails:
itemCount: 42
responses:
'200':
description: Successful response containing the updated playlist resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Playlist'
examples:
YoutubePlaylistsUpdate200Example:
summary: Default youtube.playlists.update 200 response
x-microcks-default: true
value:
kind: youtube#video
etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
id: abc123def456
snippet:
publishedAt: '2026-01-15T10:30:00Z'
channelId: '500123'
title: Example Title
description: A sample description for this resource.
thumbnails: example_value
channelTitle: example_value
tags:
# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/youtube/refs/heads/main/openapi/youtube-data-api-openapi.yml