openapi: 3.2.0
info:
  title: Gumlet Channel Viewers API
  description: Gumlet helps developers deliver online video and images. This API encompasses Gumlet Video, Image and Video Analytics functionality to help you build your products better and faster than ever before.
  version: '1.4'
  contact:
    name: Gumlet Support Team
    url: https://www.gumlet.com/contact/
    email: support@gumlet.com
  termsOfService: https://www.gumlet.com/terms/
  license:
    name: Apache 2.0
    url: https://opensource.org/license/apache-2.0
  x-scalar-sdk-installation:
  - lang: TypeScript
    description: '```sh

      npm install @gumlet/nodejs-sdk

      ```'
  - lang: Python
    description: '```sh

      pip install gumlet

      ```'
servers:
- url: https://api.gumlet.com/v1
security:
- API_KEY: []
tags:
- name: Channel Viewers
  description: Invite and remove viewers on a private video channel.
paths:
  /channel/{video_workspace_id}/viewers/invite:
    post:
      summary: Invite Channel Viewers
      description: Invite one or more viewers to a members-only channel.
      operationId: invite-channel-viewers
      parameters:
      - in: path
        name: video_workspace_id
        description: Gumlet workspace ID. You can get it on Gumlet dashboard or retrieve it using list workspace API.
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - users
              properties:
                users:
                  type: array
                  description: List of viewers to invite. A maximum of 200 viewers can be invited in one request.
                  minItems: 1
                  maxItems: 200
                  items:
                    type: object
                    required:
                    - email
                    - name
                    properties:
                      email:
                        type: string
                        format: email
                        description: Viewer email address.
                      name:
                        type: string
                        minLength: 1
                        maxLength: 100
                        description: Viewer display name.
            examples:
              Request Example:
                value:
                  users:
                  - email: test@gumlet.com
                    name: Test User-0
                  - email: test+1@gumlet.com
                    name: Test User-1
                  - email: test+2@gumlet.com
                    name: Test User-2
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: true
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: invalid_email_format
                      message: One of the emails provided is in invalid format, Please provide a valid email address.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_email_format
                      message:
                        type: string
                        example: One of the emails provided is in invalid format, Please provide a valid email address.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - Channel Viewers
      x-stoplight:
        id: pynbolf5gd84k
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst channelViewer = await client.channelViewers.invite('videoWorkspaceId', {\n  users: [\n    { email: 'test@gumlet.com', name: 'Test User-0' },\n    { email: 'test+1@gumlet.com', name: 'Test User-1' },\n    { email: 'test+2@gumlet.com', name: 'Test User-2' },\n  ],\n});\n\nconsole.log(channelViewer);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nchannel_viewer = client.channel_viewers.invite(\n    video_workspace_id=\"videoWorkspaceId\",\n    users=[\n        {\"email\": \"test@gumlet.com\", \"name\": \"Test User-0\"},\n        {\"email\": \"test+1@gumlet.com\", \"name\": \"Test User-1\"},\n        {\"email\": \"test+2@gumlet.com\", \"name\": \"Test User-2\"},\n    ],\n)\n\nprint(channel_viewer)"
  /channel/{video_workspace_id}/viewers/remove:
    post:
      summary: Remove Channel Viewers
      description: Remove one or more viewers from a channel by email address.
      operationId: remove-channel-viewers
      parameters:
      - in: path
        name: video_workspace_id
        description: Gumlet workspace ID. You can get it on Gumlet dashboard or retrieve it using list workspace API.
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emails
              properties:
                emails:
                  type: array
                  description: Email addresses of viewers to remove. A maximum of 200 viewers can be removed in one request.
                  maxItems: 200
                  items:
                    type: string
                    format: email
            examples:
              Request Example:
                value:
                  emails:
                  - test@gumlet.com
                  - test+2@gumlet.com
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: true
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: invalid_channel_id
                      message: Channel id is not a vaild id.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_channel_id
                      message:
                        type: string
                        example: Channel id is not a vaild id.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - Channel Viewers
      x-stoplight:
        id: ow2emng08e9gs
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst channelViewer = await client.channelViewers.delete('videoWorkspaceId', {\n  emails: ['test@gumlet.com', 'test+2@gumlet.com'],\n});\n\nconsole.log(channelViewer);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nchannel_viewer = client.channel_viewers.delete(\n    video_workspace_id=\"videoWorkspaceId\",\n    emails=[\"test@gumlet.com\", \"test+2@gumlet.com\"],\n)\n\nprint(channel_viewer)"
  /channel/{video_workspace_id}/viewers/invite/csv:
    post:
      summary: Invite Channel Viewers via CSV
      description: Invite viewers to a channel by uploading a CSV file.
      operationId: invite-channel-viewers-csv
      parameters:
      - in: path
        name: video_workspace_id
        description: Gumlet workspace ID. You can get it on Gumlet dashboard or retrieve it using list workspace API.
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - viewers_csv
              properties:
                viewers_csv:
                  type: string
                  format: binary
                  description: 'CSV file containing viewer rows. Required columns: email, name. Maximum 500 viewers.'
            examples:
              CSV Upload:
                value:
                  viewers_csv: viewers.csv
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: true
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: csv_file_missing
                      message: CSV File is a required parameters
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: csv_file_missing
                      message:
                        type: string
                        example: CSV File is a required parameters
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          description: Payload Too Large
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: file_too_large
                      message: Uploaded file exceeds the maximum allowed size
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: file_too_large
                      message:
                        type: string
                        example: Uploaded file exceeds the maximum allowed size
                    required:
                    - code
                    - message
                required:
                - error
      tags:
      - Channel Viewers
      x-stoplight:
        id: k8pujzz5z3wov
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst channelViewer = await client.channelViewers.inviteCsv('videoWorkspaceId', {\n  viewers_csv: 'viewers.csv',\n});\n\nconsole.log(channelViewer);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nchannel_viewer = client.channel_viewers.invite_csv(\n    video_workspace_id=\"videoWorkspaceId\",\n    viewers_csv=b\"viewers.csv\",\n)\n\nprint(channel_viewer)"
  /channel/{workspace_id}/viewers:
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Subscriber ID
                        email:
                          type: string
                          description: Email ID of the subscriber
                          format: email
                        name:
                          type: string
                          description: Name of the subscriber
                        status:
                          type: string
                          description: Current status of the subscriber
                        channel_title:
                          type: string
                          description: Title of channel
                        invited_at:
                          type: string
                          description: ISO 8601 timestamp of the invitation time
                        invited_by:
                          type: string
                          description: User ID of the user who invited this subscriber
                        invitation_link:
                          type: string
                          description: URL of the invitation from where the person can accept the invite.
                      x-apidog-orders:
                      - id
                      - email
                      - name
                      - status
                      - channel_title
                      - invited_at
                      - invited_by
                      - invitation_link
                      required:
                      - id
                      - email
                      - name
                      - status
                      - channel_title
                    description: Details about subscribers
                  total_count:
                    type: integer
                    description: Number of total subscribers
                x-apidog-orders:
                - subscriptions
                - total_count
                required:
                - subscriptions
                - total_count
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: channel_not_found
                      message: Could not find any channel with specified id.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: channel_not_found
                      message:
                        type: string
                        example: Could not find any channel with specified id.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: List Subscribers
      tags:
      - Channel Viewers
      operationId: list-channel-subscribers
      description: List all channel subscribers.
      parameters:
      - in: path
        name: workspace_id
        description: Gumlet workspace ID. You can get it on Gumlet dashboard or retrieve it using list workspace API.
        schema:
          type: string
        required: true
      - in: query
        name: page_number
        schema:
          type: integer
          default: 1
          minimum: 1
          multipleOf: 1
        description: Page number to retrieve. Starts at 1.
      - in: query
        name: page_size
        schema:
          type: integer
          default: 10
          multipleOf: 1
          minimum: 1
        description: Number of items to return per page
        required: false
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst channelViewer = await client.channelViewers.listSubscribers('workspaceId', {\n  page_number: 1,\n  page_size: 10,\n});\n\nconsole.log(channelViewer);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nchannel_viewer = client.channel_viewers.list_subscribers(\n    workspace_id=\"workspaceId\",\n    page_number=1,\n    page_size=10,\n)\n\nprint(channel_viewer)"
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            param:
              type: string
              description: Optional parameter name related to the error
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid API key / bearer token
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: invalid_api_key
                  message: API key supplied with request is invalid
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden — unpaid account or insufficient role permissions
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: unauthorized
                  message: You don't have access to this feature. Please contact your organization owner.
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    API_KEY:
      type: http
      scheme: bearer
x-tagGroups:
- name: Video on Demand
  tags:
  - Video Assets
  - Global Search
  - Multipart Upload
  - Audio Upload
  - Subtitle Upload
  - Recycle Bin
  - Video Workspaces
  - Folders
  - Video Playlists
  - Channel Viewers
  - Video Usage Analytics
  - Video Profiles
  - Webhooks
- name: Live Streams
  tags:
  - Live Stream Workspaces
  - Live Stream Assets
  - Live Stream Analytics
- name: Image APIs
  tags:
  - Image Sources
  - Image Usage Analytics
- name: Video Analytics
  tags:
  - Video Analytics
- name: Webhooks
  tags:
  - Webhooks
- name: Account Endpoints
  tags:
  - User Data
  - Billing
  - Organization Data
  - Audit Logs
x-ext-urls: {}