Youtube Videos API

openapi: 3.2.0
info:
  title: Youtube Videos API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Videos 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: 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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    servers:
    - url: https://www.googleapis.com/youtube/v3
      description: YouTube Data API v3 base server
  /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
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    servers:
    - url: https://www.googleapis.com/youtube/v3
      description: YouTube Data API v3 base server
  /videos/{videoId}:
    put:
      tags:
      - Videos
      operationId: updateVideo
      summary: Youtube Update Video Metadata
      description: 'Updates a video''s metadata. This operation requires OAuth 2.0 authentication.

        You can only update videos that belong to the authenticated user''s channel.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulVideoInsertExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/VideoIdPath'
      - $ref: '#/components/parameters/Part'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoUpdateRequest'
            examples:
              VideoUpdateRequestExample:
                $ref: '#/components/examples/VideoUpdateRequestExample'
      responses:
        '200':
          description: Successfully updated video
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video_2'
              examples:
                SuccessfulVideoInsertExample:
                  $ref: '#/components/examples/SuccessfulVideoInsertExample'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
      security:
      - OAuth2:
        - https://www.googleapis.com/auth/youtube.readonly
      - ApiKey: []
    delete:
      tags:
      - Videos
      operationId: deleteVideo
      summary: Youtube Delete Video
      description: 'Deletes a video. This operation requires OAuth 2.0 authentication.

        You can only delete videos that belong to the authenticated user''s channel.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/VideoIdPath'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully deleted video
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
      security:
      - OAuth2:
        - https://www.googleapis.com/auth/youtube.readonly
      - ApiKey: []
    servers:
    - url: https://www.googleapis.com/youtube/v3
      description: YouTube Data API Production Server
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      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:
    VideoPlayer:
      type: object
      description: Information used to play the video.
      properties:
        embedHtml:
          type: string
          description: An iframe tag that embeds a player that will play the video.
          example: example_value
        embedHeight:
          type: number
          description: The height of the embedded player returned in the player.embedHtml property.
          example: 42.5
        embedWidth:
          type: number
          description: The width of the embedded player returned in the player.embedHtml property.
          example: 42.5
    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
    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
    Video:
      type: object
      description: A video resource represents a YouTube video.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#video.
          default: youtube#video
          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 video.
          example: abc123def456
        snippet:
          $ref: '#/components/schemas/VideoSnippet'
        contentDetails:
          $ref: '#/components/schemas/VideoContentDetails'
        status:
          $ref: '#/components/schemas/VideoStatus'
        statistics:
          $ref: '#/components/schemas/VideoStatistics'
        player:
          $ref: '#/components/schemas/VideoPlayer'
        localizations:
          type: object
          description: The localizations object contains translations of the video's metadata.
          additionalProperties:
            type: object
            properties:
              title:
                type: string
                description: The localized video title.
              description:
                type: string
                description: The localized video description.
          example: example_value
    VideoListResponse:
      type: object
      description: A list of video resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#videoListResponse.
          default: youtube#videoListResponse
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        nextPageToken:
          type: string
          description: The token that can be used as the pageToken parameter to retrieve the next page of results in the result set.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        prevPageToken:
          type: string
          description: The token that can be used as the pageToken parameter to retrieve the previous page of results in the result set.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        items:
          type: array
          description: A list of videos that match the request criteria.
          items:
            $ref: '#/components/schemas/Video'
          example: []
    VideoSnippet:
      type: object
      description: Basic details about a video, including its title, description, tags, and category.
      properties:
        publishedAt:
          type: string
          format: date-time
          description: The date and time when the video was published.
          example: '2026-01-15T10:30:00Z'
        channelId:
          type: string
          description: The ID of the YouTube channel that published the video.
          example: '500123'
        title:
          type: string
          description: The video title.
          example: Example Title
        description:
          type: string
          description: The video description.
          example: A sample description for this resource.
        thumbnails:
          type: object
          description: A map of thumbnail images associated with the video.
          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
        channelTitle:
          type: string
          description: The channel title of the YouTube channel that published the video.
          example: example_value
        tags:
          type: array
          description: A list of keyword tags associated with the video.
          items:
            type: string
          example: []
        categoryId:
          type: string
          description: The YouTube video category associated with the video.
          example: '500123'
        liveBroadcastContent:
          type: string
          description: Indicates if the video is an upcoming/active live broadcast.
          enum:
          - live
          - none
          - upcoming
          example: live
        defaultLanguage:
          type: string
          description: The language of the text in the video resource's snippet.title and snippet.description properties.
          example: en
        localized:
          type: object
          description: The snippet.localized object contains either a localized title and description for the video or the title in the default language.
          properties:
            title:
              type: string
              description: The localized video title.
            description:
              type: string
              description: The localized video description.
          example: example_value
    VideoContentDetails:
      type: object
      description: Information about the video content, including the length of the video and an indication of whether captions are available.
      properties:
        duration:
          type: string
          description: The length of the video in ISO 8601 format.
          example: example_value
        dimension:
          type: string
          description: Indicates whether the video is available in 3D or in 2D.
          example: example_value
        definition:
          type: string
          description: Indicates whether the video is available in high definition or standard definition.
          enum:
          - hd
          - sd
          example: hd
        caption:
          type: string
          description: Indicates whether captions are available for the video.
          enum:
          - 'false'
          - 'true'
          example: 'false'
        licensedContent:
          type: boolean
          description: Indicates whether the video represents licensed content, which means that the content has been claimed by a YouTube content partner.
          example: true
        contentRating:
          type: object
          description: Specifies the ratings that the video received under various rating schemes.
          example: example_value
    VideoStatus:
      type: object
      description: The status of an uploaded video.
      properties:
        uploadStatus:
          type: string
          description: The status of the uploaded video.
          enum:
          - deleted
          - failed
          - processed
          - rejected
          - uploaded
          example: deleted
        privacyStatus:
          type: string
          description: The video's privacy status.
          enum:
          - private
          - public
          - unlisted
          example: private
        license:
          type: string
          description: The video's license.
          enum:
          - creativeCommon
          - youtube
          example: creativeCommon
        embeddable:
          type: boolean
          description: Indicates whether the video can be embedded on another website.
          example: true
        publicStatsViewable:
          type: boolean
          description: Indicates whether the video's extended statistics on the video's watch page are publicly viewable.
          example: true
        madeForKids:
          type: boolean
          description: Indicates whether the video is designated as child-directed.
          example: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
    VideoStatistics:
      type: object
      description: Statistics about the video such as the number of times the video has been viewed or liked.
      properties:
        viewCount:
          type: string
          description: The number of times the video has been viewed.
          example: 42
        likeCount:
          type: string
          description: The number of users who have indicated that they liked the video.
          example: 42
        dislikeCount:
          type: string
          description: The number of users who have indicated that they disliked the video.
          example: 42
        favoriteCount:
          type: string
          description: The number of users who have added the video to their favorites list.
          example: 42
        commentCount:
          type: string
          description: The number of comments for the video.
          example: 42
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    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'
    VideoListResponse_2:
      type: object
      description: Response containing video resources
      required:
      - kind
      - etag
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#videoListResponse
        etag:
          type: string
          description: ETag for caching purposes
        nextPageToken:
          type: string
          description: Token for the next page of results
        prevPageToken:
          type: string
          description: Token for the previous page of results
        pageInfo:
          $ref: '#/components/schemas/PageInfo_2'
        items:
  

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/youtube/refs/heads/main/openapi/youtube-videos-api-openapi.yml