openapi: 3.1.0
info:
  title: Twitch Drops Ads Extensions API
  description: APIs for game developers to create and manage Drops campaigns that grant in-game rewards to Twitch viewers watching streamers play their game. Drops campaigns are managed through the Twitch Developer Console and fulfilled via the Helix API entitlements endpoints.
  version: '1.0'
  contact:
    name: Twitch Developer Support
    url: https://dev.twitch.tv/support/
  termsOfService: https://www.twitch.tv/p/legal/terms-of-service/
servers:
- url: https://api.twitch.tv/helix
  description: Twitch Helix API Production
security:
- oauth2: []
tags:
- name: Extensions
  description: Manage and query extension information
paths:
  /extensions:
    get:
      operationId: getExtensions
      summary: Twitch Get Extensions
      description: Gets information about an extension.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      - name: extension_id
        in: query
        required: true
        schema:
          type: string
      - name: extension_version
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Extension information returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /extensions/released:
    get:
      operationId: getReleasedExtensions
      summary: Twitch Get Released Extensions
      description: Gets information about a released extension.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      - name: extension_id
        in: query
        required: true
        schema:
          type: string
      - name: extension_version
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Released extension information returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
  /users/extensions/list:
    get:
      operationId: getUserExtensions
      summary: Twitch Get User Extensions
      description: Gets a list of all extensions (active and inactive) the broadcaster has installed.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      responses:
        '200':
          description: User extensions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InstalledExtension'
  /users/extensions:
    get:
      operationId: getUserActiveExtensions
      summary: Twitch Get User Active Extensions
      description: Gets the active extensions the broadcaster has installed.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      - name: user_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Active extensions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ActiveExtensions'
    put:
      operationId: updateUserExtensions
      summary: Twitch Update User Extensions
      description: Updates the active extensions the broadcaster has installed.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/ActiveExtensions'
      responses:
        '200':
          description: Extensions updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ActiveExtensions'
  /extensions/chat:
    post:
      operationId: sendExtensionChatMessage
      summary: Twitch Send Extension Chat Message
      description: Sends a chat message to a broadcaster's channel from the extension.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      - name: broadcaster_id
        in: query
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              - extension_id
              - extension_version
              properties:
                text:
                  type: string
                  maxLength: 280
                extension_id:
                  type: string
                extension_version:
                  type: string
      responses:
        '204':
          description: Chat message sent successfully
  /extensions/live:
    get:
      operationId: getExtensionLiveChannels
      summary: Twitch Get Extension Live Channels
      description: Gets a list of channels with an active extension, sorted by descending viewer count.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/clientId'
      - name: extension_id
        in: query
        required: true
        schema:
          type: string
      - name: first
        in: query
        schema:
          type: integer
          maximum: 100
      - name: after
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Live channels returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        broadcaster_id:
                          type: string
                        broadcaster_name:
                          type: string
                        game_name:
                          type: string
                        game_id:
                          type: string
                        title:
                          type: string
                  pagination:
                    $ref: '#/components/schemas/Pagination'
components:
  schemas:
    Pagination:
      type: object
      properties:
        cursor:
          type: string
    Extension:
      type: object
      properties:
        author_name:
          type: string
        bits_enabled:
          type: boolean
        can_install:
          type: boolean
        configuration_location:
          type: string
          enum:
          - hosted
          - custom
          - none
        description:
          type: string
        eula_tos_url:
          type: string
        has_chat_support:
          type: boolean
        icon_url:
          type: string
        icon_urls:
          type: object
          additionalProperties:
            type: string
        id:
          type: string
        name:
          type: string
        privacy_policy_url:
          type: string
        request_identity_link:
          type: boolean
        screenshot_urls:
          type: array
          items:
            type: string
        state:
          type: string
          enum:
          - Approved
          - AssetsUploaded
          - Deleted
          - Deprecated
          - InReview
          - InTest
          - PendingAction
          - Rejected
          - Released
        subscriptions_support_level:
          type: string
          enum:
          - none
          - optional
        summary:
          type: string
        support_email:
          type: string
        version:
          type: string
        viewer_summary:
          type: string
        views:
          type: object
          properties:
            mobile:
              type: object
              properties:
                viewer_url:
                  type: string
            panel:
              type: object
              properties:
                viewer_url:
                  type: string
                height:
                  type: integer
                can_link_external_content:
                  type: boolean
            video_overlay:
              type: object
              properties:
                viewer_url:
                  type: string
                can_link_external_content:
                  type: boolean
            component:
              type: object
              properties:
                viewer_url:
                  type: string
                aspect_ratio_x:
                  type: integer
                aspect_ratio_y:
                  type: integer
                autoscale:
                  type: boolean
                scale_pixels:
                  type: integer
                target_height:
                  type: integer
                can_link_external_content:
                  type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
        status:
          type: integer
        message:
          type: string
    InstalledExtension:
      type: object
      properties:
        id:
          type: string
        version:
          type: string
        name:
          type: string
        can_activate:
          type: boolean
        type:
          type: array
          items:
            type: string
            enum:
            - component
            - mobile
            - panel
            - overlay
    ActiveExtensions:
      type: object
      properties:
        panel:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ActiveExtensionSlot'
        overlay:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ActiveExtensionSlot'
        component:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ActiveExtensionSlot'
    ActiveExtensionSlot:
      type: object
      properties:
        active:
          type: boolean
        id:
          type: string
        version:
          type: string
        name:
          type: string
        x:
          type: integer
        y:
          type: integer
  responses:
    Unauthorized:
      description: Authentication required or token is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    clientId:
      name: Client-Id
      in: header
      required: true
      schema:
        type: string
      description: Your registered application's client ID
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://id.twitch.tv/oauth2/token
          scopes: {}
externalDocs:
  description: Twitch Drops Documentation
  url: https://dev.twitch.tv/docs/drops/