Youtube Subscriptions API

openapi: 3.2.0
info:
  title: Youtube Subscriptions API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Subscriptions 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: Subscriptions
  description: Operations related to YouTube channel subscriptions
paths:
  /subscriptions:
    get:
      operationId: youtube.subscriptions.list
      summary: Youtube List Subscriptions
      description: Returns subscription resources that match the API request criteria. Retrieve subscriptions for the authenticated user, a specific channel, or by subscription IDs.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/part'
      - name: id
        in: query
        description: Comma-separated list of YouTube subscription IDs for the resources being retrieved.
        schema:
          type: string
        example: abc123def456
      - name: mine
        in: query
        description: Set this parameter to true to retrieve the subscriptions of the authenticated user.
        schema:
          type: boolean
        example: true
      - name: channelId
        in: query
        description: Retrieves subscriptions for the channel with the specified YouTube channel ID.
        schema:
          type: string
        example: '500123'
      - $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 subscription resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
              examples:
                YoutubeSubscriptionsList200Example:
                  summary: Default youtube.subscriptions.list 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    prevPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    pageInfo:
                      totalResults: 42
                      resultsPerPage: 10
                    items:
                    - kind: youtube#video
                      etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                      id: abc123def456
                      snippet:
                        publishedAt: '2026-01-15T10:30:00Z'
                        title: Example Title
                        description: A sample description for this resource.
                        resourceId: {}
                        channelId: '500123'
                        thumbnails: 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.subscriptions.insert
      summary: Youtube Subscribe to a Channel
      description: Adds a subscription for the authenticated user. The authenticated user must be authorized to create subscriptions.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The subscription resource to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
            examples:
              YoutubeSubscriptionsInsertRequestExample:
                summary: Default youtube.subscriptions.insert request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    publishedAt: '2026-01-15T10:30:00Z'
                    title: Example Title
                    description: A sample description for this resource.
                    resourceId:
                      kind: youtube#video
                      channelId: '500123'
                    channelId: '500123'
                    thumbnails: example_value
      responses:
        '200':
          description: Successful response containing the newly created subscription resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              examples:
                YoutubeSubscriptionsInsert200Example:
                  summary: Default youtube.subscriptions.insert 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      publishedAt: '2026-01-15T10:30:00Z'
                      title: Example Title
                      description: A sample description for this resource.
                      resourceId:
                        kind: youtube#video
                        channelId: '500123'
                      channelId: '500123'
                      thumbnails: 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.subscriptions.delete
      summary: Youtube Unsubscribe From a Channel
      description: Deletes a subscription. The authenticated user must own the subscription being deleted.
      tags:
      - Subscriptions
      parameters:
      - name: id
        in: query
        required: true
        description: The ID of the subscription to delete.
        schema:
          type: string
        example: abc123def456
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: The subscription 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
  /subscriptions/{subscriptionId}:
    delete:
      tags:
      - Subscriptions
      operationId: deleteSubscription
      summary: Youtube Unsubscribe from Channel
      description: 'Deletes a subscription. This operation requires OAuth 2.0 authentication.

        You can only delete subscriptions that belong to the authenticated user.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdPath'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully deleted subscription
        '404':
          description: Subscription 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:
    Subscription:
      type: object
      description: A subscription resource contains information about a YouTube user's subscription to a channel.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#subscription.
          default: youtube#subscription
          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 subscription.
          example: abc123def456
        snippet:
          type: object
          description: The snippet object contains basic details about the subscription.
          properties:
            publishedAt:
              type: string
              format: date-time
              description: The date and time that the subscription was created.
            title:
              type: string
              description: The subscription title.
            description:
              type: string
              description: The subscription description.
            resourceId:
              type: object
              description: The resourceId object contains information about the resource to which the subscriber subscribed.
              properties:
                kind:
                  type: string
                  description: The type of the API resource.
                channelId:
                  type: string
                  description: The value that YouTube uses to uniquely identify the channel that the user subscribed to.
            channelId:
              type: string
              description: The ID of the channel that the subscription belongs to.
            thumbnails:
              type: object
              description: A map of thumbnail images associated with the subscription.
          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
    SubscriptionListResponse:
      type: object
      description: A list of subscription resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#subscriptionListResponse.
          default: youtube#subscriptionListResponse
          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 subscriptions that match the request criteria.
          items:
            $ref: '#/components/schemas/Subscription'
          example: []
    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
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    SubscriptionContentDetails:
      type: object
      description: Content details for the subscription
      properties:
        totalItemCount:
          type: integer
          description: Total number of videos on the channel
          example: 500
        newItemCount:
          type: integer
          description: Number of new videos since last visit
          example: 5
    SubscriptionInsertRequest:
      type: object
      description: Request body for creating a subscription
      required:
      - snippet
      properties:
        snippet:
          type: object
          required:
          - resourceId
          properties:
            resourceId:
              type: object
              required:
              - kind
              - channelId
              properties:
                kind:
                  type: string
                  example: youtube#channel
                channelId:
                  type: string
                  description: ID of the channel to subscribe to
                  example: UC_x5XG1OV2P6uZZ5FSM9Ttw
    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'
    SubscriptionSnippet:
      type: object
      description: Basic information about the subscription
      properties:
        publishedAt:
          type: string
          format: date-time
          description: When the subscription was created
          example: '2024-01-15T10:30:00Z'
        title:
          type: string
          description: Title of the subscribed channel
          example: Google Developers
        description:
          type: string
          description: Description of the subscribed channel
        resourceId:
          $ref: '#/components/schemas/ResourceId'
        channelId:
          type: string
          description: ID of the subscriber's channel
        thumbnails:
          $ref: '#/components/schemas/ThumbnailDetails'
    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
    SubscriptionListResponse_2:
      type: object
      description: Response containing subscription resources
      required:
      - kind
      - etag
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#subscriptionListResponse
        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 subscriptions
          items:
            $ref: '#/components/schemas/Subscription_2'
    ResourceId:
      type: object
      description: Identifies the resource in the search result
      required:
      - kind
      properties:
        kind:
          type: string
          description: Type of resource
          enum:
          - youtube#video
          - youtube#channel
          - youtube#playlist
          example: youtube#video
        videoId:
          type: string
          description: Video ID if the result is a video
          example: dQw4w9WgXcQ
        channelId:
          type: string
          description: Channel ID if the result is a channel
          example: UC_x5XG1OV2P6uZZ5FSM9Ttw
        playlistId:
          type: string
          description: Playlist ID if the result is a playlist
          example: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
    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'
    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
    Subscription_2:
      type: object
      description: A subscription resource
      required:
      - kind
      - etag
      - id
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#subscription
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the subscription
          example: SUBScription123abc
        snippet:
          $ref: '#/components/schemas/SubscriptionSnippet'
        contentDetails:
          $ref: '#/components/schemas/SubscriptionContentDetails'
  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
    ForChannelId:
      name: forChannelId
      in: query
      required: false
      description: Filter subscriptions to the specified channel
      schema:
        type: string
        example: UC_x5XG1OV2P6uZZ5FSM9Ttw
    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
    SubscriptionIdPath:
      name: subscriptionId
      in: path
      required: true
      description: The unique identifier of the subscription
      schema:
        type: string
        example: SUBScription123abc
    ChannelIdQuery:
      name: channelId
      in: query
      required: false
      description: Filter results by channel ID
      schema:
        type: string
        example: UC_x5XG1OV2P6uZZ5FSM9Ttw
    SubscriptionOrder:
      name: order
      in: query
      required: false
      description: The method to use for sorting subscription results
      schema:
        type: string
        enum:
        - alphabetical
        - relevance
        - unread
        default: relevance
        example: alphabetical
    AccessToken:
      name: access_token
      in: query
      required: false
      description: OAuth 2.0 access token for authentication
      schema:
        type: string
    Mine:
      name: mine
      in: query
      required: false
      description: Return resources owned by the authenticated user
      schema:
        type: boolean
        example: true
  examples:
    BadRequestErrorExample:
      summary: Bad request error
      description: Example error response for invalid parameters
      value:
        error:
          code: 400
          message: Invalid parameter value
          errors:
          - domain: youtube.parameter
            reason: invalidParameter
            message: The parameter 'part' is required
            locationType: parameter
            location: part
    SuccessfulSubscriptionInsertExample:
      summary: Successfully created subscription
      description: Example response for a new subscription
      value:
        kind: youtube#subscription
        etag: newsub123
        id: NEWsub456
        snippet:
          publishedAt: '2024-03-20T14:00:00Z'
          title: Subscribed Channel
          resourceId:
            kind: youtube#channel
            channelId: UC_x5XG1OV2P6uZZ5FSM9Ttw
          thumbnails:
            default:
              url: https://yt3.ggpht.com/channel.jpg
              width: 88
              height: 88
        contentDetails:
          totalItemCount: 500
          newItemCount: 0
    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
    SubscriptionInsertRequestExample:
      summary: Subscription creation request
      description: Example request body for subscribing to a channel
      value:
        snippet:
          resourceId:
            kind: youtube#channel
            channelId: UC_x5XG1OV2P6uZZ5FSM9Ttw
    SuccessfulSubscriptionListExample:
      summary: Successful subscription list response
      description: Example response for retrieving subscriptions
      value:
        kind: youtube#subscriptionListResponse
        etag: subs123etag
        pageInfo:
          totalResults: 50
          resultsPerPage: 5
        items:
        - kind: youtube#subscription
          etag: sub1etag
          id: SUBScription123abc
          snippet:
            publishedAt: '2024-01-15T10:30:00Z'
            title: Google Developers
            description: The Google Developers channel...
            resourceId:
              kind: youtube#channel
              channelId: UC_x5XG1OV2P6uZZ5FSM9Ttw
            thumbnails:
              default:
                url: https://yt3.ggpht.com/channel.jpg
                width: 88
                height: 88
          contentDetails:
            totalItemCount: 500
            newItemCount: 5
    UnauthorizedErrorExample:
      summary: Unauthorized error
      description: Example error response for authentication failure
      value:
        error:
          code: 401
          message: Invalid credentials
          errors:
          - domain: youtube.authentication
            reason: authError
            message: The access token is invalid or expired
            locationType: header
            location: Authorization
  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