Youtube Channels API

openapi: 3.2.0
info:
  title: Youtube Channels API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Channels across 2 of this provider''s published API definitions: youtube-data-api-openapi.yml, youtube-data-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.googleapis.com/youtube/v3
  description: YouTube Data API v3 base server
tags:
- name: Channels
  description: Operations related to YouTube channel resources
paths:
  /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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    servers:
    - url: https://www.googleapis.com/youtube/v3
      description: YouTube Data API v3 base server
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The request was authenticated but the caller does not have permission to perform the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The request was not authenticated or the credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ChannelSnippet:
      type: object
      description: Basic details about a channel, including its title, description, and thumbnails.
      properties:
        title:
          type: string
          description: The channel title.
          example: Example Title
        description:
          type: string
          description: The channel description.
          example: A sample description for this resource.
        customUrl:
          type: string
          description: The channel's custom URL.
          example: https://www.example.com
        publishedAt:
          type: string
          format: date-time
          description: The date and time that the channel was created.
          example: '2026-01-15T10:30:00Z'
        thumbnails:
          type: object
          description: A map of thumbnail images associated with the channel.
          additionalProperties:
            type: object
            properties:
              url:
                type: string
                description: The URL of the thumbnail image.
              width:
                type: integer
                description: The thumbnail width in pixels.
              height:
                type: integer
                description: The thumbnail height in pixels.
          example: example_value
        country:
          type: string
          description: The country with which the channel is associated.
          example: 42
        localized:
          type: object
          description: The snippet.localized object contains a localized title and description for the channel.
          properties:
            title:
              type: string
              description: The localized channel title.
            description:
              type: string
              description: The localized channel description.
          example: example_value
    ErrorResponse:
      type: object
      description: A standard error response returned by the YouTube Data API.
      properties:
        error:
          type: object
          description: The error details.
          properties:
            code:
              type: integer
              description: The HTTP status code of the error.
            message:
              type: string
              description: A human-readable description of the error.
            errors:
              type: array
              description: A list of individual errors.
              items:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                  domain:
                    type: string
                    description: The domain in which the error occurred.
                  reason:
                    type: string
                    description: The reason for the error.
          example: example_value
    Channel:
      type: object
      description: A channel resource represents a YouTube channel.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#channel.
          default: youtube#channel
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        id:
          type: string
          description: The ID that YouTube uses to uniquely identify the channel.
          example: abc123def456
        snippet:
          $ref: '#/components/schemas/ChannelSnippet'
        statistics:
          $ref: '#/components/schemas/ChannelStatistics'
        contentDetails:
          type: object
          description: The contentDetails object encapsulates information about the channel's content.
          properties:
            relatedPlaylists:
              type: object
              description: A map that identifies playlists associated with the channel.
              properties:
                uploads:
                  type: string
                  description: The ID of the playlist that contains the channel's uploaded videos.
                likes:
                  type: string
                  description: The ID of the playlist that contains the videos that the channel has liked.
          example: example_value
        brandingSettings:
          type: object
          description: The brandingSettings object encapsulates information about the branding of the channel.
          properties:
            channel:
              type: object
              description: Branding settings for the channel page.
              properties:
                title:
                  type: string
                  description: The channel title.
                description:
                  type: string
                  description: The channel description.
                keywords:
                  type: string
                  description: Keywords associated with the channel.
                defaultLanguage:
                  type: string
                  description: The content tab that users should display by default on the channel page.
            image:
              type: object
              description: Branding images associated with the channel page.
              properties:
                bannerExternalUrl:
                  type: string
                  description: The URL for the banner image shown on the channel page on the YouTube website.
          example: example_value
    PageInfo:
      type: object
      description: Paging details for a list operation, including information about the total number of resources and the number per page.
      properties:
        totalResults:
          type: integer
          description: The total number of results in the result set.
          example: 42
        resultsPerPage:
          type: integer
          description: The number of results included in the API response.
          example: 10
    ChannelStatistics:
      type: object
      description: Statistics about a YouTube channel.
      properties:
        viewCount:
          type: string
          description: The number of times the channel has been viewed.
          example: 42
        subscriberCount:
          type: string
          description: The number of subscribers that the channel has.
          example: 42
        hiddenSubscriberCount:
          type: boolean
          description: Indicates whether the channel's subscriber count is publicly visible.
          example: 42
        videoCount:
          type: string
          description: The number of public videos uploaded to the channel.
          example: 42
    ChannelListResponse:
      type: object
      description: A list of channel resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#channelListResponse.
          default: youtube#channelListResponse
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        nextPageToken:
          type: string
          description: The token for the next page of results.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        prevPageToken:
          type: string
          description: The token for the previous page of results.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        items:
          type: array
          description: A list of channels that match the request criteria.
          items:
            $ref: '#/components/schemas/Channel'
          example: []
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    Channel_2:
      type: object
      description: A YouTube channel resource
      required:
      - kind
      - etag
      - id
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#channel
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the channel
          example: UC_x5XG1OV2P6uZZ5FSM9Ttw
        snippet:
          $ref: '#/components/schemas/ChannelSnippet_2'
        contentDetails:
          $ref: '#/components/schemas/ChannelContentDetails'
        statistics:
          $ref: '#/components/schemas/ChannelStatistics_2'
    ThumbnailDetails:
      type: object
      description: Thumbnail images at various resolutions
      properties:
        default:
          $ref: '#/components/schemas/Thumbnail'
        medium:
          $ref: '#/components/schemas/Thumbnail'
        high:
          $ref: '#/components/schemas/Thumbnail'
        standard:
          $ref: '#/components/schemas/Thumbnail'
        maxres:
          $ref: '#/components/schemas/Thumbnail'
    Thumbnail:
      type: object
      description: A thumbnail image
      properties:
        url:
          type: string
          description: URL of the thumbnail image
          example: https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg
        width:
          type: integer
          description: Width of the thumbnail
          example: 120
        height:
          type: integer
          description: Height of the thumbnail
          example: 90
    ChannelListResponse_2:
      type: object
      description: Response containing channel resources
      required:
      - kind
      - etag
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#channelListResponse
        etag:
          type: string
          description: ETag for caching purposes
        nextPageToken:
          type: string
          description: Token for the next page of results
        pageInfo:
          $ref: '#/components/schemas/PageInfo_2'
        items:
          type: array
          description: List of channels
          items:
            $ref: '#/components/schemas/Channel_2'
    ErrorDetails:
      type: object
      description: Details about an API error
      required:
      - code
      - message
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: Invalid parameter value
        errors:
          type: array
          description: List of specific errors
          items:
            $ref: '#/components/schemas/ErrorItem'
    ChannelStatistics_2:
      type: object
      description: Statistics for the channel
      properties:
        viewCount:
          type: string
          description: Total channel views
          example: '500000000'
        subscriberCount:
          type: string
          description: Number of subscribers
          example: '3000000'
        hiddenSubscriberCount:
          type: boolean
          description: Whether subscriber count is hidden
          example: false
        videoCount:
          type: string
          description: Number of public videos
          example: '5000'
    ChannelSnippet_2:
      type: object
      description: Basic information about the channel
      properties:
        title:
          type: string
          description: Title of the channel
          example: Google Developers
        description:
          type: string
          description: Description of the channel
          example: The Google Developers channel...
        customUrl:
          type: string
          description: Custom URL for the channel
          example: '@GoogleDevelopers'
        publishedAt:
          type: string
          format: date-time
          description: When the channel was created
          example: '2007-08-23T00:34:43Z'
        thumbnails:
          $ref: '#/components/schemas/ThumbnailDetails'
        country:
          type: string
          description: Country associated with the channel
          example: US
    PageInfo_2:
      type: object
      description: Pagination information
      properties:
        totalResults:
          type: integer
          description: Total number of results
          example: 1000000
        resultsPerPage:
          type: integer
          description: Number of results per page
          example: 25
    ChannelContentDetails:
      type: object
      description: Content details for the channel
      properties:
        relatedPlaylists:
          type: object
          properties:
            likes:
              type: string
              description: Playlist ID for liked videos
            favorites:
              type: string
              description: Playlist ID for favorited videos
            uploads:
              type: string
              description: Playlist ID for uploaded videos
              example: UU_x5XG1OV2P6uZZ5FSM9Ttw
    ErrorItem:
      type: object
      description: Individual error detail
      properties:
        domain:
          type: string
          description: Error domain
          example: youtube.parameter
        reason:
          type: string
          description: Error reason code
          example: invalidParameter
        message:
          type: string
          description: Detailed error message
          example: The parameter 'part' is required
        locationType:
          type: string
          description: Type of location where error occurred
          example: parameter
        location:
          type: string
          description: Specific location of the error
          example: part
  parameters:
    maxResults:
      name: maxResults
      in: query
      description: The maximum number of items that should be returned in the result set. Acceptable values are 0 to 50, inclusive.
      schema:
        type: integer
        minimum: 0
        maximum: 50
        default: 5
    pageToken:
      name: pageToken
      in: query
      description: Identifies a specific page in the result set that should be returned. In an API response, the nextPageToken and prevPageToken properties identify other pages available.
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: Selector specifying which fields to include in a partial response. Use this parameter to reduce bandwidth usage by selecting only the fields you need.
      schema:
        type: string
    key:
      name: key
      in: query
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
      schema:
        type: string
    part:
      name: part
      in: query
      required: true
      description: Specifies a comma-separated list of one or more resource properties that the API response will include. The part parameter value must include the id property.
      schema:
        type: string
    ForUsername:
      name: forUsername
      in: query
      required: false
      description: Retrieve channel by username
      schema:
        type: string
        example: GoogleDevelopers
    Part:
      name: part
      in: query
      required: true
      description: 'The part parameter specifies a comma-separated list of one or more

        resource properties that the API response will include.

        '
      schema:
        type: string
        example: snippet,contentDetails,statistics
    ApiKey:
      name: key
      in: query
      required: false
      description: API key for authentication (for read-only operations)
      schema:
        type: string
    PageToken:
      name: pageToken
      in: query
      required: false
      description: Token for retrieving the next page of results
      schema:
        type: string
    MaxResultsDefault:
      name: maxResults
      in: query
      required: false
      description: Maximum number of items to return (1-50)
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 5
        example: 25
    ChannelIdQuery:
      name: channelId
      in: query
      required: false
      description: Filter results by channel ID
      schema:
        type: string
        example: UC_x5XG1OV2P6uZZ5FSM9Ttw
    Mine:
      name: mine
      in: query
      required: false
      description: Return resources owned by the authenticated user
      schema:
        type: boolean
        example: true
  examples:
    NotFoundErrorExample:
      summary: Not found error
      description: Example error response when resource is not found
      value:
        error:
          code: 404
          message: Resource not found
          errors:
          - domain: youtube.video
            reason: videoNotFound
            message: The video identified by the parameter id could not be found
            locationType: parameter
            location: id
    SuccessfulChannelListExample:
      summary: Successful channel list response
      description: Example response for retrieving channel details
      value:
        kind: youtube#channelListResponse
        etag: channel123etag
        pageInfo:
          totalResults: 1
          resultsPerPage: 1
        items:
        - kind: youtube#channel
          etag: ch123etag
          id: UC_x5XG1OV2P6uZZ5FSM9Ttw
          snippet:
            title: Google Developers
            description: The Google Developers channel...
            customUrl: '@GoogleDevelopers'
            publishedAt: '2007-08-23T00:34:43Z'
            thumbnails:
              default:
                url: https://yt3.ggpht.com/channel_default.jpg
                width: 88
                height: 88
            country: US
          contentDetails:
            relatedPlaylists:
              uploads: UU_x5XG1OV2P6uZZ5FSM9Ttw
          statistics:
            viewCount: '500000000'
            subscriberCount: '3000000'
            hiddenSubscriberCount: false
            videoCount: '5000'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/youtube: Manage your YouTube account
            https://www.googleapis.com/auth/youtube.readonly: View your YouTube account
            https://www.googleapis.com/auth/youtube.upload: Manage your YouTube videos
            https://www.googleapis.com/auth/youtube.force-ssl: See, edit, and permanently delete your YouTube videos, ratings, comments and captions
            https://www.googleapis.com/auth/youtubepartner: View and manage your assets and associated content on YouTube
    apiKey:
      type: apiKey
      in: query
      name: key
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for YouTube Data API
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/youtube: Manage your YouTube account
            https://www.googleapis.com/auth/youtube.readonly: View your YouTube account
            https://www.googleapis.com/auth/youtube.upload: Upload videos to YouTube
            https://www.googleapis.com/auth/youtube.force-ssl: Manage your YouTube videos
    ApiKey:
      type: apiKey
      description: API key for read-only operations
      name: key
      in: query
externalDocs:
  description: YouTube Data API Documentation
  url: https://developers.google.com/youtube/v3
x-refined-from:
- youtube-data-api-openapi.yml
- youtube-data-openapi-original.yml