openapi: 3.1.0
info:
  title: Red5 Pro Brew Mixer Admin Streams API
  description: The Red5 Pro Brew Mixer API is a REST interface for the Cauldron Media Engine that enables dynamic composition of multiple live video and audio streams into a single mixed output stream. It supports creating and managing mixers, controlling input sources and layout, and producing composite streams for broadcasting. The API provides both v1 and v2 endpoints for mixer lifecycle management and image overlay control, making it useful for virtual events, live production, and multi-participant streaming scenarios.
  version: '2.0'
  contact:
    name: Red5 Support
    url: https://www.red5.net/contact/
  termsOfService: https://www.red5.net/terms/
servers:
- url: http://{host}:5080
  description: Red5 Pro Server with Brew Mixer
  variables:
    host:
      default: localhost
      description: Hostname or IP address of the Red5 Pro server
security:
- accessToken: []
tags:
- name: Streams
  description: Live stream enumeration, statistics, and control
paths:
  /applications/{appName}/streams:
    get:
      operationId: listStreams
      summary: List Streams in an Application
      description: Returns all active live streams within the specified application scope including stream names, subscriber counts, and connection statistics.
      tags:
      - Streams
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      - $ref: '#/components/parameters/accessTokenParam'
      responses:
        '200':
          description: List of streams returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Stream'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /applications/{appName}/streams/{streamName}:
    get:
      operationId: getStream
      summary: Get Stream Details
      description: Returns detailed statistics for a specific live stream including bitrate, frame rate, subscriber count, and connection duration.
      tags:
      - Streams
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      - $ref: '#/components/parameters/streamNameParam'
      - $ref: '#/components/parameters/accessTokenParam'
      responses:
        '200':
          description: Stream details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stream'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /applications/{appName}/streams/{streamName}/action/startrecord:
    post:
      operationId: startStreamRecording
      summary: Start Recording a Stream
      description: Initiates recording of the specified live stream to disk. The recording is saved in the configured recording directory on the server.
      tags:
      - Streams
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      - $ref: '#/components/parameters/streamNameParam'
      - $ref: '#/components/parameters/accessTokenParam'
      responses:
        '200':
          description: Recording started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /applications/{appName}/streams/{streamName}/action/stoprecord:
    post:
      operationId: stopStreamRecording
      summary: Stop Recording a Stream
      description: Stops an active recording session for the specified live stream. The completed recording file is finalized and available on disk.
      tags:
      - Streams
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      - $ref: '#/components/parameters/streamNameParam'
      - $ref: '#/components/parameters/accessTokenParam'
      responses:
        '200':
          description: Recording stopped successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /streams/stream/{nodeGroupName}/publish/{streamGuid}:
    get:
      operationId: getPublishStreamEndpoint
      summary: Get Publish Stream Endpoint
      description: Returns the connection details for a publisher to connect to the correct Red5 Pro node for broadcasting a stream. The Stream Manager selects an appropriate node based on load and availability within the specified node group.
      tags:
      - Streams
      parameters:
      - $ref: '#/components/parameters/nodeGroupNameParam'
      - $ref: '#/components/parameters/streamGuidParam'
      responses:
        '200':
          description: Publish endpoint information returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          $ref: '#/components/responses/NotFound'
  /streams/stream/{nodeGroupName}/subscribe/{streamGuid}:
    get:
      operationId: getSubscribeStreamEndpoint
      summary: Get Subscribe Stream Endpoint
      description: Returns the connection details for a subscriber to connect to the correct Red5 Pro node for consuming a live stream. Routes subscribers to nodes that have the stream available within the specified node group.
      tags:
      - Streams
      parameters:
      - $ref: '#/components/parameters/nodeGroupNameParam'
      - $ref: '#/components/parameters/streamGuidParam'
      responses:
        '200':
          description: Subscribe endpoint information returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized_2:
      description: Authentication failed or bearer token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed or access token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    nodeGroupNameParam:
      name: nodeGroupName
      in: path
      description: Name of the node group (cluster) to target
      required: true
      schema:
        type: string
    streamGuidParam:
      name: streamGuid
      in: path
      description: Unique identifier (GUID) for the stream
      required: true
      schema:
        type: string
    streamNameParam:
      name: streamName
      in: path
      description: Name of the live stream
      required: true
      schema:
        type: string
    appNameParam:
      name: appName
      in: path
      description: Name of the Red5 Pro application scope
      required: true
      schema:
        type: string
    accessTokenParam:
      name: accessToken
      in: query
      description: API access token for authentication
      required: true
      schema:
        type: string
  schemas:
    ActionResponse:
      type: object
      description: Response from a stream action request
      properties:
        result:
          type: boolean
          description: True if the action was completed successfully
        message:
          type: string
          description: Human-readable result message
    Stream:
      type: object
      description: A live stream active on the Red5 Pro server
      properties:
        name:
          type: string
          description: Stream name identifier
        clientId:
          type: string
          description: ID of the publishing client connection
        subscriberCount:
          type: integer
          description: Number of active subscribers to this stream
        bytesIn:
          type: integer
          description: Total bytes received for this stream
        bytesOut:
          type: integer
          description: Total bytes sent for this stream
        duration:
          type: integer
          description: Stream duration in milliseconds
        videoCodec:
          type: string
          description: Video codec in use (e.g., H264)
        audioCodec:
          type: string
          description: Audio codec in use (e.g., AAC)
        width:
          type: integer
          description: Video frame width in pixels
        height:
          type: integer
          description: Video frame height in pixels
        fps:
          type: number
          description: Video frames per second
        videoBitrate:
          type: integer
          description: Video bitrate in bits per second
        audioBitrate:
          type: integer
          description: Audio bitrate in bits per second
    Error:
      type: object
      description: Error response
      properties:
        code:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
    StreamEndpoint:
      type: object
      description: Connection endpoint details for a publisher or subscriber
      properties:
        host:
          type: string
          description: Hostname or IP address of the Red5 Pro streaming node
        port:
          type: integer
          description: Port number for the streaming connection
        protocol:
          type: string
          description: Streaming protocol to use (rtmp, rtsp, wss)
        streamGuid:
          type: string
          description: Stream GUID
        app:
          type: string
          description: Application scope name on the target node
  securitySchemes:
    accessToken:
      type: apiKey
      in: query
      name: accessToken
      description: API access token for authenticating Brew Mixer API requests
externalDocs:
  description: Red5 Pro Brew Mixer API Documentation
  url: https://www.red5.net/docs/red5-pro/development/api/mixer/brew-mixer-api/