openapi: 3.0.3
info:
  title: Livepush Developers API
  description: |
    Official REST API reference for Livepush.

    The Livepush API allows developers to programmatically manage
    live streams, multistreaming destinations, video libraries,
    recordings, scheduling, and media ingestion workflows.

    This specification defines the base structure for all Livepush
    API resources. Some endpoints may be introduced incrementally
    as additional APIs become available.
  version: 1.0.0
  termsOfService: https://livepush.io/terms
  contact:
    name: Livepush Support
    email: support@livepush.io
    url: https://livepush.io/support
  license:
    name: Proprietary
    url: https://livepush.io/terms
servers:
  - url: https://octopus.livepush.io
    description: Core Streams & Media APIs
  - url: https://squid.livepush.io
    description: Accounts & Billing APIs
  - url: https://vod-web-import-api.livepush.io
    description: Livepush VOD Import API
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Account-level resources and metadata
  - name: Streams
    description: Live stream creation and lifecycle management
  - name: Destinations
    description: Streaming destinations (YouTube, Facebook, RTMP, etc.)
  - name: Videos
    description: Video library and VOD assets
  - name: Video Imports
    description: Import videos from direct URLs (S3, HTTPS)
  - name: Stream Recordings
    description: Recordings generated from live streams
  - name: Stream Zones
    description: Processing and storage regions
  - name: Stream Scheduler
    description: Scheduled and automated streaming
paths:
  /account/this:
    servers:
      - url: https://squid.livepush.io
        description: Accounts API server
    get:
      tags:
        - Accounts
      summary: Get user details
      description: |
        Retrieves details of the currently authenticated user account.
        The response includes profile information, preferences, and
        basic billing metadata.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current user account details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: RDHe2BXVP6d89
                  username:
                    type: string
                    example: congresstv24_xxxxx
                  name:
                    type: string
                    example: CONGRESS TV
                  email:
                    type: string
                    format: email
                    example: user@example.com
                  avatar:
                    type: string
                    format: uri
                    example: https://example.com/avatar.jpg
                  ns:
                    type: string
                    example: nsL2BzkdFKgIYv
                  isDisabled:
                    type: boolean
                    example: false
                  createdAt:
                    type: string
                    format: date-time
                  preferences:
                    type: object
                    additionalProperties: true
                  billingInfo:
                    type: object
                    properties:
                      email:
                        type: string
                        format: email
                        example: billing@example.com
                      name:
                        type: string
                        example: John Doe
        '401':
          description: Unauthorized
  /account/subscriptions:
    servers:
      - url: https://squid.livepush.io
        description: Accounts API server
    get:
      tags:
        - Accounts
      summary: Get user subscriptions
      description: |
        Returns a list of active and historical subscriptions
        associated with the authenticated user account.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of account subscriptions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: AzyzaQV4rbNdSXKQ
                    category:
                      type: string
                      example: simulcast
                    startTime:
                      type: string
                      format: date-time
                    endTime:
                      type: string
                      format: date-time
                    updatedAt:
                      type: string
                      format: date-time
                    plan:
                      type: object
                      properties:
                        id:
                          type: string
                          example: plan_editors_monthly
                        name:
                          type: string
                          example: Editors Plan
                        category:
                          type: string
                          example: simulcast
                        description:
                          type: string
                          example: Best for broadcasters and media teams
                        cost:
                          type: number
                          example: 39
                        planDuration:
                          type: integer
                          example: 30
                        isPublic:
                          type: boolean
                          example: true
                        features:
                          type: array
                          items:
                            type: object
                            properties:
                              key:
                                type: string
                                example: destinations
                              value:
                                oneOf:
                                  - type: number
                                  - type: string
                              category:
                                type: string
                                example: simulcast
                        grants:
                          type: object
                          additionalProperties: true
        '401':
          description: Unauthorized
  /streams/mine:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Streams
      summary: Get user streams
      description: |
        Returns the list of live streams owned by the authenticated user.
        Each stream includes its configuration, assigned zone, metadata,
        and connected streaming destinations.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of user streams
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: st_xxxxxxxxxxxxx
                    metadata:
                      type: object
                      properties:
                        name:
                          type: string
                          example: OUTPUT 1
                        category:
                          type: string
                          description: Stream category
                          enum:
                            - simulcast
                            - schedule
                          example: simulcast
                    createdAt:
                      type: string
                      format: date-time
                    isDisabled:
                      type: boolean
                      example: false
                    config:
                      type: object
                      properties:
                        pullUrlMaxRetry:
                          type: integer
                          example: 5
                        recordingTier:
                          type: string
                          example: rise
                    destinations:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            example: pb_xxxxxxxxxxxx
                          label:
                            type: string
                            example: YouTube
                          appName:
                            type: string
                            example: youtube
                          rtmpBase:
                            type: string
                            example: rtmp://a.rtmp.youtube.com/live2
                          isDisabled:
                            type: boolean
                            example: true
                    zone:
                      type: object
                      properties:
                        id:
                          type: string
                          example: zn_xxxxxxxxx
                        name:
                          type: string
                          example: Livepush Global
                        category:
                          type: string
                          example: simulcast
                        host:
                          type: string
                          example: stream.livepush.io
                        isPublic:
                          type: boolean
                          example: true
                        isDefault:
                          type: boolean
                          example: true
        '401':
          description: Unauthorized
  /streams:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    post:
      tags:
        - Streams
      summary: Create a new stream
      description: |
        Creates a new live stream for the authenticated user.
        The stream is initialized with the provided category and name
        and is assigned to a default processing zone.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - category
                - name
              properties:
                category:
                  type: string
                  description: Stream category
                  enum:
                    - simulcast
                    - schedule
                  example: simulcast
                name:
                  type: string
                  description: Display name for the stream
                  example: Luke Skywalker Apricot Fascinating
      responses:
        '201':
          description: Stream created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: st_xxxxxxxxxxxxx
                  chatId:
                    type: string
                    example: mc_xxxxxxxxxxxx
                  embedId:
                    type: string
                    example: em_xxxxxxxxxxxx
                  createdAt:
                    type: string
                    format: date-time
                  metadata:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Luke Skywalker Apricot Fascinating
                      category:
                        type: string
                        enum:
                          - simulcast
                          - schedule
                        example: simulcast
                  config:
                    type: object
                    properties:
                      pullUrlMaxRetry:
                        type: integer
                        example: 5
                      recordingTier:
                        type: string
                        example: rise
                  destinations:
                    type: array
                    items:
                      type: object
                  zone:
                    type: string
                    description: Assigned processing zone ID
                    example: zn_xxxxxxxxx
                  unsafeContent:
                    type: boolean
                    example: true
                  hasValidated:
                    type: boolean
                    example: true
        '400':
          description: Invalid request payload
        '401':
          description: Unauthorized
  /streams/{streamId}:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Streams
      summary: Get stream by ID
      description: |
        Retrieves details of a specific live stream owned by the
        authenticated user. The response includes stream metadata,
        configuration, zone assignment, and destinations.
      security:
        - bearerAuth: []
      parameters:
        - name: streamId
          in: path
          required: true
          description: Unique identifier of the stream
          schema:
            type: string
            example: st_xxxxxxxxxxxxx
      responses:
        '200':
          description: Stream details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: st_xxxxxxxxxxxxx
                  chatId:
                    type: string
                    example: mc_xxxxxxxxxxxx
                  embedId:
                    type: string
                    example: em_xxxxxxxxxxxx
                  createdAt:
                    type: string
                    format: date-time
                  metadata:
                    type: object
                    properties:
                      name:
                        type: string
                        example: OUTPUT 1
                      category:
                        type: string
                        description: Stream category
                        enum:
                          - simulcast
                          - schedule
                        example: simulcast
                  config:
                    type: object
                    properties:
                      pullUrlMaxRetry:
                        type: integer
                        example: 5
                      recordingTier:
                        type: string
                        example: rise
                  destinations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: pb_xxxxxxxxxxxx
                        label:
                          type: string
                          example: YouTube
                        appName:
                          type: string
                          example: youtube
                        rtmpBase:
                          type: string
                          example: rtmp://a.rtmp.youtube.com/live2
                        isDisabled:
                          type: boolean
                          example: true
                        updatedAt:
                          type: string
                          format: date-time
                  zone:
                    type: object
                    properties:
                      id:
                        type: string
                        example: zn_xxxxxxxxx
                      name:
                        type: string
                        example: Livepush Global
                      category:
                        type: string
                        example: simulcast
                      host:
                        type: string
                        example: stream.livepush.io
                      isPublic:
                        type: boolean
                        example: true
                      isDefault:
                        type: boolean
                        example: true
                  unsafeContent:
                    type: boolean
                    example: true
                  hasValidated:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
    delete:
      tags:
        - Streams
      summary: Delete live stream
      description: |
        Permanently deletes a live stream owned by the authenticated user.

        Once deleted, the live stream configuration, associated destinations,
        and related metadata will be removed and cannot be recovered.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Live stream deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
  /streams/{stream_id}/config/scheduler/playlist:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    put:
      tags:
        - Stream Scheduler
      summary: Attach Videos to the Pre-Recorded Stream Playlist
      description: |
        Attaches one or more existing videos to the scheduler playlist
        of a pre-recorded live stream.

        The playlist defines the playback order for scheduled or looping
        pre-recorded live streams.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the pre-recorded live stream
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - videos
              properties:
                videos:
                  type: array
                  description: List of video IDs to attach to the playlist
                  items:
                    type: string
      responses:
        '200':
          description: Scheduler playlist updated successfully
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
  /streams/{stream_id}/config/scheduler/loop:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    put:
      tags:
        - Stream Scheduler
      summary: Configure scheduler looping
      description: |
        Enables or disables looping for the scheduler playlist.

        When enabled, the playlist will repeat indefinitely, allowing
        continuous 24/7 pre-recorded live streaming.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the pre-recorded live stream
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - enabled
              properties:
                enabled:
                  type: boolean
                  description: Whether playlist looping is enabled
      responses:
        '200':
          description: Scheduler looping configuration updated
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
  /streams/{stream_id}/config/scheduler/events:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    post:
      tags:
        - Stream Scheduler
      summary: Schedule a pre-recorded live stream
      description: |
        Schedules a pre-recorded live stream to start at a specific
        date and time using the configured playlist.

        This endpoint is used for both one-time scheduled events
        and looping (24/7) streams.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the pre-recorded live stream
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
                - datetime
              properties:
                label:
                  type: string
                  description: Human-readable label for the scheduled event
                datetime:
                  type: string
                  format: date-time
                  description: Scheduled start time in ISO 8601 (UTC)
                immediateStart:
                  type: boolean
                  description: Whether the stream should start immediately
                loop:
                  type: boolean
                  description: Whether the event respects looping configuration
                videos:
                  type: array
                  description: Optional list of video IDs for this event
                  items:
                    type: string
      responses:
        '200':
          description: Stream scheduled successfully
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
  /streams/{stream_id}/config/scheduler/events/{event_id}:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    delete:
      tags:
        - Stream Scheduler
      summary: Delete scheduled stream event
      description: |
        Deletes a scheduled pre-recorded live stream event before it starts.

        This operation does not affect the stream configuration or playlist.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the pre-recorded live stream
          schema:
            type: string
        - name: event_id
          in: path
          required: true
          description: Unique identifier of the scheduled event
          schema:
            type: string
      responses:
        '200':
          description: Scheduled event deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Stream or event not found
  /streams/{stream_id}/config/scheduler/events/{event_id}/end:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    put:
      tags:
        - Stream Scheduler
      summary: End active scheduled stream
      description: |
        Stops a currently running pre-recorded live stream event.

        Ending a stream is not instantaneous and may take a few seconds
        to fully stop playback and disconnect destinations.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the pre-recorded live stream
          schema:
            type: string
        - name: event_id
          in: path
          required: true
          description: Unique identifier of the active scheduled event
          schema:
            type: string
      responses:
        '200':
          description: Stream end request accepted
        '401':
          description: Unauthorized
        '404':
          description: Stream or event not found
  /streams/me/destinations:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Destinations
      summary: List saved destinations
      description: |
        Returns the list of saved streaming destinations owned by the
        authenticated user.

        Saved destinations can be used for multistreaming and may include
        platforms such as YouTube, Facebook, or custom RTMP endpoints.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of saved destinations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StreamDestination'
        '401':
          description: Unauthorized
  /streams/{stream_id}/destinations:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    post:
      tags:
        - Destinations
      summary: Create new stream destination
      description: |
        Creates and attaches a new streaming destination to the specified
        live stream.

        This endpoint is used to add platforms such as YouTube, Facebook,
        or custom RTMP destinations to an existing live stream.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the live stream
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
                - appName
                - rtmpBase
                - rtmpKey
              properties:
                label:
                  type: string
                  description: Human-readable name for the destination
                appName:
                  type: string
                  description: Destination platform identifier (e.g. youtube, facebook)
                rtmpBase:
                  type: string
                  description: Base RTMP ingest URL
                rtmpKey:
                  type: string
                  description: RTMP stream key
      responses:
        '200':
          description: Stream destination created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamDestination'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
  /streams/{stream_id}/destinations/{destination_id}/enable:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    put:
      tags:
        - Destinations
      summary: Enable stream destination
      description: |
        Enables a previously added destination for the specified live stream.

        Once enabled, the destination will start receiving the live stream
        when the stream is online.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the live stream
          schema:
            type: string
        - name: destination_id
          in: path
          required: true
          description: Unique identifier of the stream destination
          schema:
            type: string
      responses:
        '200':
          description: Stream destination enabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
        '404':
          description: Stream or destination not found
  /streams/{stream_id}/destinations/{destination_id}/disable:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    put:
      tags:
        - Destinations
      summary: Disable stream destination
      description: |
        Disables an active destination for the specified live stream.

        When disabled, the destination will no longer receive the live stream
        until it is re-enabled.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the live stream
          schema:
            type: string
        - name: destination_id
          in: path
          required: true
          description: Unique identifier of the stream destination
          schema:
            type: string
      responses:
        '200':
          description: Stream destination disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
        '404':
          description: Stream or destination not found
  /streams/{stream_id}/destinations/{destination_id}:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    delete:
      tags:
        - Destinations
      summary: Delete stream destination
      description: |
        Permanently deletes a destination from the specified live stream.

        Once deleted, the destination will be removed entirely and can no
        longer be enabled or reused.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the live stream
          schema:
            type: string
        - name: destination_id
          in: path
          required: true
          description: Unique identifier of the stream destination
          schema:
            type: string
      responses:
        '200':
          description: Stream destination deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
        '404':
          description: Stream or destination not found
  /streams/me/videos:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Videos
      summary: Get user videos
      description: |
        Returns the list of video assets owned by the authenticated user.
        These videos can be used for pre-recorded live streams, scheduling,
        or other video-based workflows.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of user videos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VideoItem'
        '401':
          description: Unauthorized
  /inspector/get_metadata:
    servers:
      - url: https://vod-web-import-api.livepush.io
        description: Livepush VOD Import API
    post:
      summary: Inspect remote video metadata
      description: |
        Inspects a video hosted at a direct URL (e.g. Amazon S3, HTTPS)
        and returns metadata required before starting a video import.

        This step is mandatory before creating a transfer.
      operationId: inspectVideoMetadata
      tags:
        - Video Imports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataRequest'
            examples:
              s3:
                $ref: '#/components/examples/MetadataRequestExample'
      responses:
        '200':
          description: Metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
              examples:
                default:
                  $ref: '#/components/examples/MetadataResponseExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transfers/new:
    servers:
      - url: https://vod-web-import-api.livepush.io
        description: Livepush VOD Import API
    post:
      summary: Start a new video import
      description: |
        Starts an asynchronous video import using the metadata ID
        returned by the inspector endpoint.
      operationId: createVideoImport
      tags:
        - Video Imports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferCreateRequest'
            examples:
              default:
                $ref: '#/components/examples/TransferCreateRequestExample'
      responses:
        '200':
          description: Import queued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferCreateResponse'
              examples:
                default:
                  $ref: '#/components/examples/TransferCreateResponseExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transfers/queued:
    servers:
      - url: https://vod-web-import-api.livepush.io
        description: Livepush VOD Import API
    get:
      summary: List queued video imports
      description: |
        Returns video imports that are currently queued or processing.

        If a previously created video ID is no longer present,
        the import is considered complete and the video will
        appear in the VOD library.
      operationId: listQueuedVideoImports
      tags:
        - Video Imports
      responses:
        '200':
          description: List of queued imports
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueuedTransfer'
              examples:
                default:
                  $ref: '#/components/examples/QueuedTransferListExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /streams/me/recordings:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Stream Recordings
      summary: List user stream recordings
      description: |
        Returns the list of stream recordings owned by the authenticated user.

        These recordings are generated from live streams and may include
        completed, queued, or errored recording entries.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of user stream recordings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recording'
        '401':
          description: Unauthorized
  /streams/{stream_id}/recordings:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Stream Recordings
      summary: List stream recordings by stream
      description: |
        Returns the list of recordings generated for a specific live stream.

        This endpoint is useful for retrieving all historical recordings
        associated with a single stream.
      security:
        - bearerAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          description: Unique identifier of the live stream
          schema:
            type: string
      responses:
        '200':
          description: List of stream recordings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recording'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
  /zones/simulcast:
    servers:
      - url: https://octopus.livepush.io
        description: Core Streams & Media APIs
    get:
      tags:
        - Stream Zones
      summary: List available rtmp ingestion zones
      description: |
        Returns the list of available stream zones that can be used for
        simulcast and stream deployment.

        Zones represent geographic regions and infrastructure locations
        available for publishing and routing live streams.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of available simulcast zones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Zone'
        '401':
          description: Unauthorized
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    MetadataRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Direct URL to the source video
          example: https://bucket.s3.amazonaws.com/video.mp4
    MetadataResponse:
      type: object
      properties:
        id:
          type: string
          description: Metadata identifier used for import
          example: tup_eK9_VlyyRnLr
        duration:
          type: number
          example: 312
        size:
          type: number
          example: 104857600
        container:
          type: string
          example: mov
        videoCodec:
          type: string
          example: h264
        audioCodec:
          type: string
          example: aac
    TransferCreateRequest:
      type: object
      required:
        - id
        - zone
        - videoName
      properties:
        id:
          type: string
          description: Metadata ID returned from inspector
          example: tup_eK9_VlyyRnLr
        zone:
          type: string
          description: Processing or storage zone
          example: zn_35hk0gxy_pr
        videoName:
          type: string
          description: Display name for the imported video
          example: how-to-stream-custom-rtmp.mov
    TransferCreateResponse:
      type: object
      properties:
        transferId:
          type: string
          example: tr_92aFxxQ
        status:
          type: string
          example: queued
    QueuedTransfer:
      type: object
      properties:
        transferId:
          type: string
          example: tr_92aFxxQ
        id:
          type: string
          example: tup_eK9_VlyyRnLr
        videoName:
          type: string
          example: how-to-stream-custom-rtmp.mov
        progress:
          type: number
          example: 64
        status:
          type: string
          example: processing
    Error:
      type: object
      properties:
        message:
          type: string
          example: Invalid request
    DestinationOAuthConfig:
      type: object
      properties:
        keepDefaultTitles:
          type: boolean
        titlesSource:
          type: string
          enum:
            - original
            - stream-titles
            - custom
        title:
          type: string
        description:
          type: string
        privacy:
          type: string
        autoStart:
          type: boolean
        autoStop:
          type: boolean
        rewind:
          type: boolean
        plannedStartTime:
          type: string
          format: date-time
        metadata:
          type: object
        userAppDetails:
          type: object
    StreamDestination:
      type: object
      description: Streaming destination
      properties:
        id:
          type: string
          example: pb_xxxxxxxxx
        appName:
          type: string
          example: youtube
        label:
          type: string
        rtmpBase:
          type: string
        oauth:
          $ref: '#/components/schemas/DestinationOAuthConfig'
        updatedAt:
          type: string
          format: date-time
        isPinned:
          type: boolean
        isDisabled:
          type: boolean
    VideoCodecType:
      type: string
      enum:
        - video
        - audio
    VideoItemMediaInfoCodec:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/VideoCodecType'
        codec:
          type: string
    VideoItemMediaInfo:
      type: object
      properties:
        hasAudioTrack:
          type: boolean
        duration:
          type: number
        width:
          type: integer
        height:
          type: integer
        fps:
          type: number
        codecs:
          type: array
          items:
            $ref: '#/components/schemas/VideoItemMediaInfoCodec'
        tracks:
          type: array
          items:
            type: object
    VideoItem:
      type: object
      description: Video asset
      properties:
        id:
          type: string
          example: vd_xxxxxxxxx
        label:
          type: string
        uploadName:
          type: string
        size:
          type: number
        mediaInfo:
          $ref: '#/components/schemas/VideoItemMediaInfo'
        zone:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        isDisabled:
          type: boolean
        tags:
          type: array
          items:
            type: string
        mediaInfoEncoded:
          $ref: '#/components/schemas/VideoItemMediaInfo'
    Recording:
      type: object
      description: Represents a recorded output generated from a live stream.
      properties:
        id:
          type: string
          description: Public identifier of the recording
          example: recLuF0EKePs
        _id:
          type: string
          description: Internal database identifier
          example: 6956c9137a06c9debc18863e
        user:
          type: string
          description: User identifier who owns the recording
          example: 0PoArI-B3
        stream:
          type: string
          description: Live stream identifier associated with the recording
          example: stZ-mQc33cFxfeRH
        streamKey:
          type: string
          description: RTMP stream key used during the recording session
        time:
          type: string
          format: date-time
          description: Time when the recording session started
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp of the recording
        sourceReadyAt:
          type: string
          format: date-time
          description: Time when the recording source became available
        duration:
          type: number
          format: float
          description: Duration of the recording in seconds
          example: 390.465
        size:
          type: number
          nullable: true
          description: Size of the recording file in bytes
        queued:
          type: boolean
          description: Indicates whether the recording is queued for processing
        unlocked:
          type: boolean
          description: Indicates whether the recording is unlocked for access
        watchable:
          type: boolean
          description: Indicates whether the recording can be played
        exportable:
          type: boolean
          description: Indicates whether the recording can be exported
        cleanable:
          type: boolean
          description: Indicates whether the recording is eligible for cleanup
        cleaned:
          type: boolean
          description: Indicates whether the recording has been cleaned
        recordingTier:
          type: string
          description: Recording tier associated with the account
          example: c_startup
        vendor:
          type: string
          description: Backend vendor handling the recording
          example: flu
        sourceHost:
          type: string
          description: Internal source host handling the recording
        ns:
          type: string
          description: Namespace identifier
        preKey:
          type: string
          description: Internal object storage key for the recording file
        screenshot:
          type: string
          nullable: true
          description: Screenshot URL or identifier for the recording
        error:
          type: string
          nullable: true
          description: Error message if recording processing failed
        isRecordingDisabled:
          type: boolean
          description: Indicates whether recording was disabled for the stream
        mediaInfo:
          type: object
          description: Technical media metadata of the recording
          properties:
            codec:
              type: string
              example: h264
            profile:
              type: string
              example: Main
            fps:
              type: number
              example: 30
            width:
              type: integer
              example: 1920
            height:
              type: integer
              example: 1080
            pix_fmt:
              type: string
              example: yuv420p
    ZoneCategory:
      type: string
      enum:
        - simulcast
        - schedule
        - rec
        - webcam
        - vod
    ZoneConfigDeploymentType:
      type: string
      enum:
        - none
        - api
    ZoneRecordingTier:
      type: string
      enum:
        - basic
        - medium
        - large
        - custom
    ZoneConfig:
      type: object
      properties:
        deploymentType:
          $ref: '#/components/schemas/ZoneConfigDeploymentType'
        publishPort:
          type: integer
          example: 1935
        publishPath:
          type: string
        supportsPullUrl:
          type: boolean
        supportsDestinationPublish:
          type: boolean
        storageId:
          type: string
        videosNamespace:
          type: string
        recordingTier:
          $ref: '#/components/schemas/ZoneRecordingTier'
    ZoneMetadata:
      type: object
      properties:
        uiSort:
          type: number
        flagId:
          type: string
        data:
          type: object
          additionalProperties: true
    Zone:
      type: object
      description: Processing or storage zone
      properties:
        id:
          type: string
        category:
          $ref: '#/components/schemas/ZoneCategory'
        name:
          type: string
        host:
          type: string
        boundHosts:
          type: array
          items:
            type: string
        config:
          $ref: '#/components/schemas/ZoneConfig'
        metadata:
          $ref: '#/components/schemas/ZoneMetadata'
        isPublic:
          type: boolean
        isPremiumZone:
          type: boolean
        isDisabled:
          type: boolean
        isArchived:
          type: boolean
        isDefault:
          type: boolean
    ScheduledEvent:
      type: object
      description: Scheduled playback event
      properties:
        id:
          type: string
          example: ev_xxxxxxxxx
        label:
          type: string
        immediateStart:
          type: boolean
        datetime:
          type: string
          format: date-time
        datetimeEnd:
          type: string
          format: date-time
        datetimeEndExplicit:
          type: boolean
        repeatCount:
          type: integer
        videos:
          type: array
          items:
            type: string
        loop:
          type: boolean
        isActive:
          type: boolean
        isArchived:
          type: boolean
        runtime:
          type: integer
          description: Runtime in seconds
        immediateEnd:
          type: boolean
        finishedAt:
          type: integer
        preciseStart:
          type: boolean
        revision:
          type: integer
        stream:
          type: string
        user:
          type: string
        awaiting:
          type: boolean
    StreamSchedulerConfig:
      type: object
      properties:
        mode:
          type: string
        videos:
          type: array
          items:
            type: string
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledEvent'
        loop:
          type: boolean
    LiveEventConfig:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        datetime:
          type: string
          format: date-time
    LiveEventStatus:
      type: string
      enum:
        - started
        - ended
    MultiChatConfig:
      type: object
      properties:
        theme:
          type: string
        textSize:
          type: string
        bgColor:
          type: string
        bgTransparency:
          type: number
        disableAvatar:
          type: boolean
        disableDates:
          type: boolean
    EmbedChatConfig:
      type: object
      properties:
        isEnabled:
          type: boolean
        readonly:
          type: boolean
        adminLoginName:
          type: string
        adminLoginPassword:
          type: string
          writeOnly: true
        greetingText:
          type: string
        bannedWords:
          type: string
    EmbedPluginsConfig:
      type: object
      properties:
        ga:
          type: string
        motamo:
          type: string
        motamoSiteID:
          type: string
        segment:
          type: string
        mixpanel:
          type: string
        kissmetrics:
          type: string
        intercom:
          type: string
    StreamMetadata:
      type: object
      properties:
        category:
          type: string
          enum:
            - simulcast
            - schedule
        name:
          type: string
    StreamConfig:
      type: object
      properties:
        pullUrl:
          type: string
          format: uri
        pullUrlMaxRetry:
          type: integer
          example: 5
        isRecordingDisabled:
          type: boolean
        hasInternalRecording:
          type: boolean
        preventRecordingAutoUpgrade:
          type: boolean
        recordingWithEmbedKey:
          type: boolean
        recordingTier:
          type: string
        schedulerConfig:
          $ref: '#/components/schemas/StreamSchedulerConfig'
        liveEventConfig:
          $ref: '#/components/schemas/LiveEventConfig'
        liveEventStatus:
          $ref: '#/components/schemas/LiveEventStatus'
        chatConfig:
          $ref: '#/components/schemas/MultiChatConfig'
        embedChatConfig:
          $ref: '#/components/schemas/EmbedChatConfig'
        embedPluginsConfig:
          $ref: '#/components/schemas/EmbedPluginsConfig'
        embedDisabled:
          type: boolean
        embedDomains:
          type: array
          items:
            type: string
        embedAutoplay:
          type: boolean
        embedTitle:
          type: string
        embedOfflineText:
          type: string
        embedLiveRewind:
          type: boolean
        maxConcurrentViewers:
          type: integer
        autoStopBroadcast:
          type: boolean
        hlsSegmentDuration:
          type: integer
        hlsSegmentCount:
          type: integer
    EmbedRouterConfig:
      type: object
      properties:
        hostname:
          type: string
        rewindMins:
          type: integer
        useDedicatedOutput:
          type: boolean
    Stream:
      type: object
      description: Live stream entity
      properties:
        id:
          type: string
          example: st_xxxxxxxxx
        ns:
          type: string
        chatId:
          type: string
        embedId:
          type: string
        metadata:
          $ref: '#/components/schemas/StreamMetadata'
        zone:
          type: string
        config:
          $ref: '#/components/schemas/StreamConfig'
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/StreamDestination'
        embedRouterConfig:
          $ref: '#/components/schemas/EmbedRouterConfig'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isDisabled:
          type: boolean
        unsafeContent:
          type: boolean
        hasValidated:
          type: boolean
    Subscription:
      type: object
      description: User subscription
      properties:
        id:
          type: string
        category:
          type: string
        user:
          type: string
        parent:
          type: string
        plan:
          type: object
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        grantsExtended:
          type: object
        metadata:
          type: object
          additionalProperties: true
        isDisabled:
          type: boolean
        isTrial:
          type: boolean
        updatedAt:
          type: string
          format: date-time
        unsubscribed:
          type: boolean
        unsubscribedAt:
          type: string
          format: date-time
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  examples:
    MetadataRequestExample:
      summary: Inspect S3 video
      value:
        url: https://bucket.s3.amazonaws.com/how-to-stream-custom-rtmp.mov
    MetadataResponseExample:
      summary: Metadata response
      value:
        id: tup_eK9_VlyyRnLr
        duration: 312
        size: 104857600
        container: mov
        videoCodec: h264
        audioCodec: aac
    TransferCreateRequestExample:
      summary: Start video import
      value:
        id: tup_eK9_VlyyRnLr
        zone: zn_35hk0gxy_pr
        videoName: how-to-stream-custom-rtmp.mov
    TransferCreateResponseExample:
      summary: Import queued
      value:
        transferId: tr_92aFxxQ
        status: queued
    QueuedTransferListExample:
      summary: Queued imports
      value:
        - transferId: tr_92aFxxQ
          id: tup_eK9_VlyyRnLr
          videoName: how-to-stream-custom-rtmp.mov
          progress: 64
