openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Room Compositions API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Rooms Compositions operations.
  name: Room Compositions
paths:
  /room_compositions:
    get:
      description: ''
      operationId: ListRoomCompositions
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[date_created_at][eq], filter[date_created_at][gte], filter[date_created_at][lte], filter[session_id], filter[status]'
        explode: true
        in: query
        name: filter
        required: false
        schema:
          properties:
            date_created_at:
              properties:
                eq:
                  description: ISO 8601 date for filtering room compositions created on that date.
                  example: '2021-04-25'
                  format: date
                  type: string
                gte:
                  description: ISO 8601 date for filtering room compositions created on or after that date.
                  example: '2021-04-25'
                  format: date
                  type: string
                lte:
                  description: ISO 8601 date for filtering room compositions created on or before that date.
                  example: '2021-04-25'
                  format: date
                  type: string
              type: object
            session_id:
              description: The session_id for filtering room compositions.
              example: 92e7d459-bcc5-4386-9f5f-6dd14a82588d
              format: uuid
              type: string
            status:
              description: The status for filtering room compositions.
              enum:
              - completed
              - processing
              - enqueued
              example: completed
              type: string
          type: object
        style: deepObject
      - $ref: '#/components/parameters/video_PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/ListRoomCompositionsResponse'
        4XX:
          $ref: '#/components/responses/video_GenericErrorResponse'
      summary: View a list of room compositions.
      tags:
      - Room Compositions
      x-endpoint-cost: medium
      x-latency-category: responsive
    post:
      description: Asynchronously create a room composition.
      operationId: CreateRoomComposition
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoomCompositionRequest'
        description: Parameters that can be defined during room composition creation.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/CreateRoomCompositionResponse'
        '422':
          $ref: '#/components/responses/video_UnprocessableEntity'
      summary: Create a room composition.
      tags:
      - Room Compositions
      x-endpoint-cost: heavy
      x-latency-category: responsive
  /room_compositions/{room_composition_id}:
    delete:
      description: Synchronously delete a room composition.
      operationId: DeleteRoomComposition
      parameters:
      - description: The unique identifier of a room composition.
        in: path
        name: room_composition_id
        required: true
        schema:
          example: 5219b3af-87c6-4c08-9b58-5a533d893e21
          format: uuid
          type: string
      responses:
        '204':
          description: The resource was deleted successfully.
        '404':
          $ref: '#/components/responses/video_ResourceNotFound'
      summary: Delete a room composition.
      tags:
      - Room Compositions
      x-endpoint-cost: medium
      x-latency-category: responsive
    get:
      operationId: ViewRoomComposition
      parameters:
      - description: The unique identifier of a room composition.
        in: path
        name: room_composition_id
        required: true
        schema:
          example: 5219b3af-87c6-4c08-9b58-5a533d893e21
          format: uuid
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GetRoomCompositionResponse'
        '404':
          $ref: '#/components/responses/video_ResourceNotFound'
      summary: View a room composition.
      tags:
      - Room Compositions
      x-endpoint-cost: light
      x-latency-category: responsive
components:
  schemas:
    video_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/video_Error'
          type: array
      type: object
    PaginationMeta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      type: object
    video_Error:
      properties:
        code:
          type: string
        detail:
          type: string
        meta:
          additionalProperties: true
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
      type: object
    RoomComposition:
      example:
        completed_at: '2022-02-25T05:39:56.377426Z'
        download_url: https://example.com
        duration_secs: 84
        ended_at: '2022-02-24T23:22:24.577677Z'
        format: mp4
        id: 7103dc53-ee59-4b54-a58b-c77d99ceb037
        record_type: composition
        resolution: 1280x720
        room_id: f981dbb3-228a-44e9-ac54-e87f0e2658b0
        session_id: 8f728d7b-00e2-4c59-8c27-f564b828df87
        size_mb: 6
        started_at: '2022-02-24T23:21:00.077209Z'
        status: enqueued
        user_id: 12a04ec9-0f91-4a91-9f3a-a19d9931182e
        video_layout:
          first:
            height: 720
            video_sources:
            - 7b61621f-62e0-4aad-ab11-9fd19e272e73
            width: 1280
            x_pos: 0
            y_pos: 0
            z_pos: 0
        webhook_event_url: https://webhook.site/544663ce-b692-4f9c-80ed-e5ad97cd5c02
      properties:
        completed_at:
          description: ISO 8601 timestamp when the room composition has completed.
          example: '2021-03-26T17:51:59.588408Z'
          format: date-time
          type: string
        created_at:
          description: ISO 8601 timestamp when the room composition was created.
          example: '2021-03-26T17:51:59.588408Z'
          format: date-time
          type: string
        download_url:
          description: Url to download the composition.
          example: https://www.example.com
          type: string
        duration_secs:
          description: Shows the room composition duration in seconds.
          example: 67
          type: integer
        ended_at:
          description: ISO 8601 timestamp when the room composition has ended.
          example: '2021-03-26T17:51:59.588408Z'
          format: date-time
          type: string
        format:
          description: Shows format of the room composition.
          enum:
          - mp4
          example: mp4
          type: string
        id:
          description: A unique identifier for the room composition.
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777f0
          format: uuid
          type: string
        record_type:
          example: room_composition
          readOnly: true
          type: string
        resolution:
          description: The resolution of the room composition.
          example: 1280x720
          type: string
        room_id:
          description: Identify the room associated with the room composition.
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
          format: uuid
          type: string
        session_id:
          description: Identify the room session associated with the room composition.
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
          format: uuid
          type: string
        size_mb:
          description: Shows the room composition size in MB.
          example: 10.5
          format: float
          type: number
        started_at:
          description: ISO 8601 timestamp when the room composition has stated.
          example: '2021-03-26T17:51:59.588408Z'
          format: date-time
          type: string
        status:
          description: Shows the room composition status.
          enum:
          - completed
          - enqueued
          - processing
          example: completed
          type: string
        updated_at:
          description: ISO 8601 timestamp when the room composition was updated.
          example: '2021-03-26T17:51:59.588408Z'
          format: date-time
          type: string
        user_id:
          description: Identify the user associated with the room composition.
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
          format: uuid
          type: string
        video_layout:
          additionalProperties:
            $ref: '#/components/schemas/VideoRegion'
          description: Describes the video layout of the room composition in terms of regions. Limited to 2 regions.
          type: object
        webhook_event_failover_url:
          default: ''
          description: The failover URL where webhooks related to this room composition will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.
          example: https://failover.example.com
          format: uri
          type: string
        webhook_event_url:
          description: The URL where webhooks related to this room composition will be sent. Must include a scheme, such as 'https'.
          example: https://example.com
          format: uri
          type: string
        webhook_timeout_secs:
          default: null
          description: Specifies how many seconds to wait before timing out a webhook.
          example: 25
          maximum: 30
          minimum: 0
          type: integer
      type: object
    CreateRoomCompositionRequest:
      properties:
        format:
          default: mp4
          description: The desired format of the room composition.
          example: mp4
          type: string
        resolution:
          default: 1280x720
          description: The desired resolution (width/height in pixels) of the resulting video of the room composition. Both width and height are required to be between 16 and 1280; and width * height should not exceed 1280 * 720
          example: 800x600
          type: string
        session_id:
          description: id of the room session associated with the room composition.
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
          format: uuid
          type: string
        video_layout:
          additionalProperties:
            $ref: '#/components/schemas/VideoRegion'
          description: Describes the video layout of the room composition in terms of regions.
          type: object
        webhook_event_failover_url:
          default: ''
          description: The failover URL where webhooks related to this room composition will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.
          example: https://failover.example.com
          format: uri
          type: string
        webhook_event_url:
          description: The URL where webhooks related to this room composition will be sent. Must include a scheme, such as 'https'.
          example: https://example.com
          format: uri
          type: string
        webhook_timeout_secs:
          default: null
          description: Specifies how many seconds to wait before timing out a webhook.
          example: 25
          maximum: 30
          minimum: 0
          type: integer
      type: object
    VideoRegion:
      properties:
        height:
          description: Height of the video region
          example: 360
          minimum: 16
          type: integer
        max_columns:
          description: Maximum number of columns of the region's placement grid. By default, the region has as many columns as needed to layout all the specified video sources.
          example: 3
          maximum: 1000
          minimum: 1
          type: integer
        max_rows:
          description: Maximum number of rows of the region's placement grid. By default, the region has as many rows as needed to layout all the specified video sources.
          example: 3
          maximum: 1000
          minimum: 1
          type: integer
        video_sources:
          description: Array of video recording ids to be composed in the region. Can be "*" to specify all video recordings in the session
          items:
            example: 7b61621f-62e0-4aad-ab11-9fd19e272e73
            format: uuid
            type: string
          type: array
        width:
          description: Width of the video region
          example: 480
          minimum: 16
          type: integer
        x_pos:
          default: 0
          description: X axis value (in pixels) of the region's upper left corner relative to the upper left corner of the whole room composition viewport.
          example: 100
          type: integer
        y_pos:
          default: 0
          description: Y axis value (in pixels) of the region's upper left corner relative to the upper left corner of the whole room composition viewport.
          example: 100
          type: integer
        z_pos:
          default: 0
          description: Regions with higher z_pos values are stacked on top of regions with lower z_pos values
          example: 1
          maximum: 99
          minimum: -99
          type: integer
      type: object
  responses:
    video_ResourceNotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/video_Error'
      description: Resource not found
    video_GenericErrorResponse:
      content:
        application/json:
          schema:
            properties:
              message:
                example: Error
                type: string
              success:
                example: false
                type: boolean
            type: object
      description: Unexpected error
    CreateRoomCompositionResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/RoomComposition'
            type: object
      description: Create room composition response.
    video_UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/video_Errors'
      description: Unprocessable entity. Check the 'detail' field in response for details.
    GetRoomCompositionResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/RoomComposition'
            type: object
      description: Get room composition response.
    ListRoomCompositionsResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/RoomComposition'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: List room compositions response.
  parameters:
    video_PageConsolidated:
      description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
      explode: true
      in: query
      name: page
      schema:
        properties:
          number:
            default: 1
            description: The page number to load.
            minimum: 1
            type: integer
          size:
            default: 20
            description: The size of the page.
            maximum: 250
            minimum: 1
            type: integer
        type: object
      style: deepObject
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http