Youtube Comments API

openapi: 3.2.0
info:
  title: Youtube Comments API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Comments 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: Comments
  description: Operations related to individual YouTube comments
paths:
  /comments:
    get:
      operationId: youtube.comments.list
      summary: Youtube List Comments
      description: Returns a list of comments that match the API request parameters. Use the part parameter to specify the comment resource properties to include in the response.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/part'
      - name: id
        in: query
        description: Comma-separated list of comment IDs for the resources being retrieved.
        schema:
          type: string
        example: abc123def456
      - name: parentId
        in: query
        description: Identifies the comment thread whose comments are being listed. Required unless the id parameter specifies comment IDs directly.
        schema:
          type: string
        example: '500123'
      - name: textFormat
        in: query
        description: Specifies whether the API should return comments formatted as HTML or plain text.
        schema:
          type: string
          enum:
          - html
          - plainText
        example: html
      - $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 comment resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListResponse'
              examples:
                YoutubeCommentsList200Example:
                  summary: Default youtube.comments.list 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    pageInfo:
                      totalResults: 42
                      resultsPerPage: 10
                    items:
                    - kind: youtube#video
                      etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                      id: abc123def456
                      snippet:
                        textOriginal: example_value
                        textDisplay: example_value
                        authorDisplayName: example_value
                        authorProfileImageUrl: https://www.example.com
                        authorChannelUrl: https://www.example.com
                        authorChannelId: {}
                        likeCount: 42
                        viewerRating: example_value
                        publishedAt: '2026-01-15T10:30:00Z'
                        updatedAt: '2026-01-15T10:30:00Z'
                        videoId: '500123'
                        parentId: '500123'
                        canRate: true
                        moderationStatus: heldForReview
        '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.comments.insert
      summary: Youtube Create a Comment
      description: Creates a reply to an existing comment. To add a top-level comment to a video or channel discussion, use the commentThreads.insert method.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The comment resource to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
            examples:
              YoutubeCommentsInsertRequestExample:
                summary: Default youtube.comments.insert request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    textOriginal: example_value
                    textDisplay: example_value
                    authorDisplayName: example_value
                    authorProfileImageUrl: https://www.example.com
                    authorChannelUrl: https://www.example.com
                    authorChannelId:
                      value: example_value
                    likeCount: 42
                    viewerRating: example_value
                    publishedAt: '2026-01-15T10:30:00Z'
                    updatedAt: '2026-01-15T10:30:00Z'
                    videoId: '500123'
                    parentId: '500123'
                    canRate: true
                    moderationStatus: heldForReview
      responses:
        '200':
          description: Successful response containing the newly created comment resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              examples:
                YoutubeCommentsInsert200Example:
                  summary: Default youtube.comments.insert 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      textOriginal: example_value
                      textDisplay: example_value
                      authorDisplayName: example_value
                      authorProfileImageUrl: https://www.example.com
                      authorChannelUrl: https://www.example.com
                      authorChannelId:
                        value: example_value
                      likeCount: 42
                      viewerRating: example_value
                      publishedAt: '2026-01-15T10:30:00Z'
                      updatedAt: '2026-01-15T10:30:00Z'
                      videoId: '500123'
                      parentId: '500123'
                      canRate: true
                      moderationStatus: heldForReview
        '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.comments.update
      summary: Youtube Update a Comment
      description: Modifies a comment. The authenticated user must own the comment being updated.
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The comment resource with updated properties.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
            examples:
              YoutubeCommentsUpdateRequestExample:
                summary: Default youtube.comments.update request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    textOriginal: example_value
                    textDisplay: example_value
                    authorDisplayName: example_value
                    authorProfileImageUrl: https://www.example.com
                    authorChannelUrl: https://www.example.com
                    authorChannelId:
                      value: example_value
                    likeCount: 42
                    viewerRating: example_value
                    publishedAt: '2026-01-15T10:30:00Z'
                    updatedAt: '2026-01-15T10:30:00Z'
                    videoId: '500123'
                    parentId: '500123'
                    canRate: true
                    moderationStatus: heldForReview
      responses:
        '200':
          description: Successful response containing the updated comment resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              examples:
                YoutubeCommentsUpdate200Example:
                  summary: Default youtube.comments.update 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      textOriginal: example_value
                      textDisplay: example_value
                      authorDisplayName: example_value
                      authorProfileImageUrl: https://www.example.com
                      authorChannelUrl: https://www.example.com
                      authorChannelId:
                        value: example_value
                      likeCount: 42
                      viewerRating: example_value
                      publishedAt: '2026-01-15T10:30:00Z'
                      updatedAt: '2026-01-15T10:30:00Z'
                      videoId: '500123'
                      parentId: '500123'
                      canRate: true
                      moderationStatus: heldForReview
        '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.comments.delete
      summary: Youtube Delete a Comment
      description: Deletes a comment. The authenticated user must own the comment or be authorized to delete it.
      tags:
      - Comments
      parameters:
      - name: id
        in: query
        required: true
        description: The ID of the comment to delete.
        schema:
          type: string
        example: abc123def456
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: The comment 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
  /comments/setModerationStatus:
    post:
      operationId: youtube.comments.setModerationStatus
      summary: Youtube Set Comment Moderation Status
      description: Sets the moderation status of one or more comments. The authenticated user must be authorized to moderate comments for the associated video or channel.
      tags:
      - Comments
      parameters:
      - name: id
        in: query
        required: true
        description: Comma-separated list of comment IDs to set moderation status for.
        schema:
          type: string
        example: abc123def456
      - name: moderationStatus
        in: query
        required: true
        description: Identifies the new moderation status. Acceptable values are heldForReview, published, and rejected.
        schema:
          type: string
          enum:
          - heldForReview
          - published
          - rejected
        example: heldForReview
      - name: banAuthor
        in: query
        description: Set to true to ban the comment author from making future comments on the channel or video.
        schema:
          type: boolean
        example: true
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: The moderation status was successfully updated.
        '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
  /commentThreads:
    get:
      tags:
      - Comments
      operationId: listCommentThreads
      summary: Youtube List Comment Threads
      description: 'Returns a list of comment threads that match the API request parameters.

        Comment threads contain the top-level comment and all replies to that comment.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulCommentThreadListExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/Part'
      - $ref: '#/components/parameters/VideoIdQuery'
      - $ref: '#/components/parameters/ChannelIdQuery'
      - $ref: '#/components/parameters/CommentThreadId'
      - $ref: '#/components/parameters/CommentOrder'
      - $ref: '#/components/parameters/MaxResultsDefault'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Successful comment threads list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentThreadListResponse'
              examples:
                SuccessfulCommentThreadListExample:
                  $ref: '#/components/examples/SuccessfulCommentThreadListExample'
        '404':
          description: Video or channel 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:
    Comment:
      type: object
      description: A comment resource contains information about a single YouTube comment.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#comment.
          default: youtube#comment
          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 comment.
          example: abc123def456
        snippet:
          type: object
          description: The snippet object contains basic details about the comment.
          properties:
            textOriginal:
              type: string
              description: The original text of the comment as it was initially posted.
            textDisplay:
              type: string
              description: The comment text as displayed to users.
            authorDisplayName:
              type: string
              description: The display name of the user who posted the comment.
            authorProfileImageUrl:
              type: string
              description: The URL for the avatar of the user who posted the comment.
            authorChannelUrl:
              type: string
              description: A link to the YouTube channel of the comment's author.
            authorChannelId:
              type: object
              description: An object that encapsulates information about the comment author's YouTube channel.
              properties:
                value:
                  type: string
                  description: The author's YouTube channel ID.
            likeCount:
              type: integer
              description: The total number of likes that the comment has received.
            viewerRating:
              type: string
              description: The rating the viewer has given to this comment. Note that this property does not currently identify dislike ratings.
            publishedAt:
              type: string
              format: date-time
              description: The date and time when the comment was originally published.
            updatedAt:
              type: string
              format: date-time
              description: The date and time when the comment was last updated.
            videoId:
              type: string
              description: The ID of the video the comment refers to.
            parentId:
              type: string
              description: The unique ID of the parent comment.
            canRate:
              type: boolean
              description: Indicates whether the current viewer can rate the comment.
            moderationStatus:
              type: string
              description: The comment's moderation status.
              enum:
              - heldForReview
              - likelySpam
              - published
              - rejected
          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
    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
    CommentListResponse:
      type: object
      description: A list of comment resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#commentListResponse.
          default: youtube#commentListResponse
          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
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        items:
          type: array
          description: A list of comments that match the request criteria.
          items:
            $ref: '#/components/schemas/Comment'
          example: []
    Comment_2:
      type: object
      description: A comment resource
      properties:
        kind:
          type: string
          example: youtube#comment
        etag:
          type: string
        id:
          type: string
          example: UgzYABCdef123xyz456
        snippet:
          $ref: '#/components/schemas/CommentSnippet'
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    CommentSnippet:
      type: object
      description: Basic information about the comment
      properties:
        authorDisplayName:
          type: string
          description: Display name of the comment author
          example: John Doe
        authorProfileImageUrl:
          type: string
          description: URL of the author's profile image
        authorChannelUrl:
          type: string
          description: URL of the author's channel
        authorChannelId:
          type: object
          properties:
            value:
              type: string
        textDisplay:
          type: string
          description: Display text of the comment
          example: Great tutorial! Very helpful.
        textOriginal:
          type: string
          description: Original text of the comment
        publishedAt:
          type: string
          format: date-time
          example: '2024-03-15T12:30:00Z'
        updatedAt:
          type: string
          format: date-time
        likeCount:
          type: integer
          example: 25
    CommentThreadListResponse:
      type: object
      description: Response containing comment thread resources
      required:
      - kind
      - etag
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#commentThreadListResponse
        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 comment threads
          items:
            $ref: '#/components/schemas/CommentThread'
    CommentThreadReplies:
      type: object
      description: Replies to the comment thread
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/Comment_2'
    CommentThread:
      type: object
      description: A comment thread resource
      required:
      - kind
      - etag
      - id
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#commentThread
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the comment thread
          example: UgzYABCdef123xyz456
        snippet:
          $ref: '#/components/schemas/CommentThreadSnippet'
        replies:
          $ref: '#/components/schemas/CommentThreadReplies'
    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'
    CommentThreadSnippet:
      type: object
      description: Basic information about the comment thread
      properties:
        channelId:
          type: string
          description: ID of the channel associated with the comment
          example: UC_x5XG1OV2P6uZZ5FSM9Ttw
        videoId:
          type: string
          description: ID of the video the comment is for
          example: dQw4w9WgXcQ
        topLevelComment:
          $ref: '#/components/schemas/Comment_2'
        canReply:
          type: boolean
          description: Whether the user can reply
          example: true
        totalReplyCount:
          type: integer
          description: Total number of replies
          example: 10
        isPublic:
          type: boolean
          description: Whether the comment thread is public
          example: true
    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
    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
    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
    CommentOrder:
      name: order
      in: query
      required: false
      description: The method to use for sorting comments
      schema:
        type: string
        enum:
        - time
        - relevance
        default: time
        example: relevance
    ChannelIdQuery:
      name: channelId
      in: query
      required: false
      description: Filter results by channel ID
      schema:
        type: string
        example: UC_x5XG1OV2P6uZZ5FSM9Ttw
    VideoIdQuery:
      name: videoId
      in: query
      required: false
      description: Filter results by video ID
      schema:
        type: string
        example: dQw4w9WgXcQ
    CommentThreadId:
      name: id
      in: query
      required: false
      description: A comma-separated list of comment thread IDs
      schema:
        type: string
        example: UgzYABCdef123xyz456
  examples:
    SuccessfulCommentThreadListExample:
      summary: Successful comment threads response
      description: Example response for retrieving comments
      value:
        kind: youtube#commentThreadListResponse
        etag: comments123etag
        pageInfo:
          totalResults: 2500
          resultsPerPage: 20
        items:
        - kind: youtube#commentThread
          etag: thread1etag
          id: UgzYABCdef123xyz456
          snippet:
            channelId: UC_x5XG1OV2P6uZZ5FSM9Ttw
            videoId: dQw4w9WgXcQ
            topLevelComment:
              kind: youtube#comment
              etag: comment1etag
              id: UgzYABCdef123xyz456
              snippet:
                authorDisplayName: John Doe
                authorProfileImageUrl: https://yt3.ggpht.com/user.jpg
                textDisplay: Great tutorial! Very helpful.
                textOriginal: Great tutorial! Very helpful.
                publishedAt: '2024-03-15T12:30:00Z'
                likeCount: 25
            canReply: true
            totalReplyCount: 10
            isPublic: true
    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
    

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