Youtube Captions API

openapi: 3.2.0
info:
  title: Youtube Captions API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Captions 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: Captions
  description: Operations related to YouTube video caption tracks
paths:
  /captions:
    get:
      operationId: youtube.captions.list
      summary: Youtube List Caption Tracks
      description: Returns a list of caption tracks that are associated with a specified video. The API response does not contain the actual captions and the captions.download method can be used to retrieve a caption track.
      tags:
      - Captions
      parameters:
      - $ref: '#/components/parameters/part'
      - name: videoId
        in: query
        required: true
        description: The ID of the video for which the API should return caption tracks.
        schema:
          type: string
        example: '500123'
      - name: id
        in: query
        description: Comma-separated list of caption track IDs to retrieve.
        schema:
          type: string
        example: abc123def456
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: Successful response containing a list of caption track resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptionListResponse'
              examples:
                YoutubeCaptionsList200Example:
                  summary: Default youtube.captions.list 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    items:
                    - kind: youtube#video
                      etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                      id: abc123def456
                      snippet:
                        videoId: '500123'
                        lastUpdated: '2026-01-15T10:30:00Z'
                        trackKind: asr
                        language: en
                        name: Example Title
                        audioTrackType: commentary
                        isCC: true
                        isLarge: true
                        isEasyReader: true
                        isDraft: true
                        isAutoSynced: true
                        status: failed
        '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.captions.insert
      summary: Youtube Upload a Caption Track
      description: Uploads a caption track. The authenticated user must own the video associated with the caption track. This method supports media upload.
      tags:
      - Captions
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The caption resource to upload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Caption'
            examples:
              YoutubeCaptionsInsertRequestExample:
                summary: Default youtube.captions.insert request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    videoId: '500123'
                    lastUpdated: '2026-01-15T10:30:00Z'
                    trackKind: asr
                    language: en
                    name: Example Title
                    audioTrackType: commentary
                    isCC: true
                    isLarge: true
                    isEasyReader: true
                    isDraft: true
                    isAutoSynced: true
                    status: failed
      responses:
        '200':
          description: Successful response containing the newly uploaded caption resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Caption'
              examples:
                YoutubeCaptionsInsert200Example:
                  summary: Default youtube.captions.insert 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      videoId: '500123'
                      lastUpdated: '2026-01-15T10:30:00Z'
                      trackKind: asr
                      language: en
                      name: Example Title
                      audioTrackType: commentary
                      isCC: true
                      isLarge: true
                      isEasyReader: true
                      isDraft: true
                      isAutoSynced: true
                      status: failed
        '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.captions.update
      summary: Youtube Update a Caption Track
      description: Updates a caption track. When updating a caption track, you can change the track's draft status, upload a new caption file, or both.
      tags:
      - Captions
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The caption resource with updated properties.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Caption'
            examples:
              YoutubeCaptionsUpdateRequestExample:
                summary: Default youtube.captions.update request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    videoId: '500123'
                    lastUpdated: '2026-01-15T10:30:00Z'
                    trackKind: asr
                    language: en
                    name: Example Title
                    audioTrackType: commentary
                    isCC: true
                    isLarge: true
                    isEasyReader: true
                    isDraft: true
                    isAutoSynced: true
                    status: failed
      responses:
        '200':
          description: Successful response containing the updated caption resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Caption'
              examples:
                YoutubeCaptionsUpdate200Example:
                  summary: Default youtube.captions.update 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      videoId: '500123'
                      lastUpdated: '2026-01-15T10:30:00Z'
                      trackKind: asr
                      language: en
                      name: Example Title
                      audioTrackType: commentary
                      isCC: true
                      isLarge: true
                      isEasyReader: true
                      isDraft: true
                      isAutoSynced: true
                      status: failed
        '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.captions.delete
      summary: Youtube Delete a Caption Track
      description: Deletes a specified caption track. The authenticated user must own the video that the caption track is associated with.
      tags:
      - Captions
      parameters:
      - name: id
        in: query
        required: true
        description: The ID of the caption track to delete.
        schema:
          type: string
        example: abc123def456
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: The caption track 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
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:
    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
    CaptionListResponse:
      type: object
      description: A list of caption resources associated with the specified video.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#captionListResponse.
          default: youtube#captionListResponse
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        items:
          type: array
          description: A list of captions that match the request criteria.
          items:
            $ref: '#/components/schemas/Caption'
          example: []
    Caption:
      type: object
      description: A caption resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#caption.
          default: youtube#caption
          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 caption track.
          example: abc123def456
        snippet:
          type: object
          description: The snippet object contains basic details about the caption.
          properties:
            videoId:
              type: string
              description: The ID of the video that the caption track is associated with.
            lastUpdated:
              type: string
              format: date-time
              description: The date and time when the caption track was last updated.
            trackKind:
              type: string
              description: The caption track's type.
              enum:
              - asr
              - forced
              - standard
            language:
              type: string
              description: The language of the caption track. The property value is a BCP-47 language tag.
            name:
              type: string
              description: The name of the caption track.
            audioTrackType:
              type: string
              description: The type of audio track associated with the caption track.
              enum:
              - commentary
              - descriptive
              - primary
              - unknown
            isCC:
              type: boolean
              description: Indicates whether the track contains closed captions for the deaf and hard of hearing.
            isLarge:
              type: boolean
              description: Indicates whether the caption track uses large text for the vision-impaired.
            isEasyReader:
              type: boolean
              description: Indicates whether caption track is formatted for easy reader.
            isDraft:
              type: boolean
              description: Indicates whether the caption track is a draft.
            isAutoSynced:
              type: boolean
              description: Indicates whether YouTube synchronized the caption track to the audio track in the video.
            status:
              type: string
              description: The caption track's status.
              enum:
              - failed
              - serving
              - syncing
          example: example_value
    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'
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    CaptionListResponse_2:
      type: object
      description: Response containing caption track resources
      required:
      - kind
      - etag
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#captionListResponse
        etag:
          type: string
          description: ETag for caching purposes
        items:
          type: array
          description: List of caption tracks
          items:
            $ref: '#/components/schemas/Caption_2'
    Caption_2:
      type: object
      description: A caption track resource
      required:
      - kind
      - etag
      - id
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#caption
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the caption track
          example: CAPTIONabc123
        snippet:
          $ref: '#/components/schemas/CaptionSnippet'
    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
    CaptionSnippet:
      type: object
      description: Basic information about the caption track
      properties:
        videoId:
          type: string
          description: ID of the video
          example: dQw4w9WgXcQ
        lastUpdated:
          type: string
          format: date-time
          description: When the caption was last updated
        trackKind:
          type: string
          description: Type of caption track
          enum:
          - ASR
          - forced
          - standard
          example: standard
        language:
          type: string
          description: Language of the caption track
          example: en
        name:
          type: string
          description: Name of the caption track
          example: English
        audioTrackType:
          type: string
          description: Type of audio track
          enum:
          - commentary
          - descriptive
          - primary
          - unknown
          example: primary
        isCC:
          type: boolean
          description: Whether this is closed caption
          example: true
        isLarge:
          type: boolean
          description: Whether the track has large text
          example: false
        isEasyReader:
          type: boolean
          description: Whether the track is easy reader
          example: false
        isDraft:
          type: boolean
          description: Whether the track is a draft
          example: false
        isAutoSynced:
          type: boolean
          description: Whether the track is auto-synced
          example: false
        status:
          type: string
          description: Status of the caption track
          enum:
          - failed
          - serving
          - syncing
          example: serving
  parameters:
    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
    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
    CaptionId:
      name: id
      in: query
      required: false
      description: A comma-separated list of caption track IDs
      schema:
        type: string
        example: CAPTIONabc123
    VideoIdQueryRequired:
      name: videoId
      in: query
      required: true
      description: The video ID to retrieve captions for
      schema:
        type: string
        example: dQw4w9WgXcQ
  examples:
    SuccessfulCaptionListExample:
      summary: Successful caption list response
      description: Example response for retrieving video captions
      value:
        kind: youtube#captionListResponse
        etag: captions123etag
        items:
        - kind: youtube#caption
          etag: caption1etag
          id: CAPTIONabc123
          snippet:
            videoId: dQw4w9WgXcQ
            lastUpdated: '2024-03-15T10:30:00Z'
            trackKind: standard
            language: en
            name: English
            audioTrackType: primary
            isCC: true
            isLarge: false
            isEasyReader: false
            isDraft: false
            isAutoSynced: false
            status: serving
    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
  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