Telnyx Room Compositions API

Rooms Compositions operations.

GitHub OpenAPI

Operations 4

GET /room_compositions View a list of room compositions #
POST /room_compositions Create a room composition #
DELETE /room_compositions/{room_composition_id} Delete a room composition #
GET /room_compositions/{room_composition_id} View a room composition #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/telnyx:telnyx-room-compositions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

telnyx-room-compositions-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Telnyx Room Compositions API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Room Compositions across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Room Compositions
  description: Rooms Compositions operations.
paths:
  /room_compositions:
    get:
      summary: View a list of room compositions
      description: Returns a paginated list of room compositions. Filter compositions by creation date, room session, or processing status.
      operationId: ListRoomCompositions
      x-endpoint-cost: medium
      tags:
      - Room Compositions
      parameters:
      - name: filter
        in: query
        style: deepObject
        explode: true
        required: false
        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]'
        schema:
          type: object
          properties:
            date_created_at:
              type: object
              properties:
                eq:
                  type: string
                  format: date
                  example: '2021-04-25'
                  description: ISO 8601 date for filtering room compositions created on that date.
                gte:
                  type: string
                  format: date
                  example: '2021-04-25'
                  description: ISO 8601 date for filtering room compositions created on or after that date.
                lte:
                  type: string
                  format: date
                  example: '2021-04-25'
                  description: ISO 8601 date for filtering room compositions created on or before that date.
            session_id:
              type: string
              format: uuid
              example: 92e7d459-bcc5-4386-9f5f-6dd14a82588d
              description: The session_id for filtering room compositions.
            status:
              type: string
              example: completed
              enum:
              - completed
              - processing
              - enqueued
              description: The status for filtering room compositions.
      - $ref: '#/components/parameters/video_PageConsolidated'
      responses:
        '200':
          description: List room compositions response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoomComposition'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        4XX:
          $ref: '#/components/responses/video_GenericErrorResponse'
    post:
      summary: Create a room composition
      description: Asynchronously create a room composition.
      operationId: CreateRoomComposition
      tags:
      - Room Compositions
      x-endpoint-cost: heavy
      requestBody:
        description: Parameters that can be defined during room composition creation.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoomCompositionRequest'
      responses:
        '202':
          description: Composition request accepted. Poll GET /room_compositions/{room_composition_id} with the returned id until the composition completes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RoomComposition'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /room_compositions/{room_composition_id}:
    delete:
      summary: Delete a room composition
      description: Synchronously delete a room composition.
      operationId: DeleteRoomComposition
      tags:
      - Room Compositions
      x-endpoint-cost: medium
      parameters:
      - name: room_composition_id
        in: path
        description: The unique identifier of a room composition.
        required: true
        schema:
          type: string
          format: uuid
          example: 5219b3af-87c6-4c08-9b58-5a533d893e21
      responses:
        '204':
          description: The resource was deleted successfully.
        '404':
          $ref: '#/components/responses/video_ResourceNotFound'
    get:
      summary: View a room composition
      operationId: ViewRoomComposition
      tags:
      - Room Compositions
      x-endpoint-cost: light
      parameters:
      - name: room_composition_id
        in: path
        description: The unique identifier of a room composition.
        required: true
        schema:
          type: string
          format: uuid
          example: 5219b3af-87c6-4c08-9b58-5a533d893e21
      responses:
        '200':
          description: Get room composition response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RoomComposition'
        '404':
          $ref: '#/components/responses/video_ResourceNotFound'
      description: Returns the composition identified by `room_composition_id`, including its room and session, processing status, media details, video layout, lifecycle timestamps, and download URL.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  responses:
    video_GenericErrorResponse:
      description: Unexpected error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Error
    video_ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/video_Error'
          example:
            code: string
            title: string
            detail: string
            source:
              pointer: string
              parameter: string
    UnprocessableEntity:
      description: Unprocessable entity. Check the 'detail' field in response for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: '10027'
              title: Unprocessable Entity
              detail: The server understood the syntax of the request but was unable to process the instructions.
    GetRoomCompositionResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/RoomComposition'
            type: object
      description: Get 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.
    video_ResourceNotFound_2:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/video_Error'
      description: Resource not found
    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.
    CreateRoomCompositionResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/RoomComposition'
            type: object
      description: Create room composition response.
    video_UnprocessableEntity_2:
      description: Unprocessable entity. Check the 'detail' field in response for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors_2'
          example:
            errors:
            - code: '10027'
              title: Unprocessable Entity
              detail: The server understood the syntax of the request but was unable to process the instructions.
  schemas:
    CreateRoomCompositionRequest:
      type: object
      properties:
        format:
          description: The desired format of the room composition.
          type: string
          example: mp4
          default: mp4
        resolution:
          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
          type: string
          example: 800x600
          default: 1280x720
        session_id:
          description: id of the room session associated with the room composition.
          type: string
          format: uuid
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
        video_layout:
          description: Describes the video layout of the room composition in terms of regions.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/VideoRegion'
        webhook_event_url:
          type: string
          format: uri
          description: The URL where webhooks related to this room composition will be sent. Must include a scheme, such as 'https'.
          example: https://example.com
        webhook_event_failover_url:
          type: string
          format: uri
          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
          default: ''
        webhook_timeout_secs:
          type: integer
          minimum: 0
          maximum: 30
          description: Specifies how many seconds to wait before timing out a webhook.
          example: 25
          default: null
    RoomComposition:
      type: object
      properties:
        id:
          description: A unique identifier for the room composition.
          type: string
          format: uuid
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777f0
        room_id:
          description: Identify the room associated with the room composition.
          type: string
          format: uuid
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
        session_id:
          description: Identify the room session associated with the room composition.
          type: string
          format: uuid
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
        user_id:
          description: Identify the user associated with the room composition.
          type: string
          format: uuid
          example: 0ccc7b54-4df3-4bca-a65a-3da1ecc777b0
        status:
          description: Shows the room composition status.
          type: string
          example: completed
          enum:
          - completed
          - enqueued
          - processing
        size_mb:
          description: Shows the room composition size in MB.
          type: number
          format: float
          example: 10.5
        download_url:
          description: Url to download the composition.
          type: string
          example: https://www.example.com
        duration_secs:
          description: Shows the room composition duration in seconds.
          type: integer
          example: 67
        format:
          description: Shows format of the room composition.
          type: string
          example: mp4
          enum:
          - mp4
        created_at:
          description: ISO 8601 timestamp when the room composition was created.
          type: string
          format: date-time
          example: '2021-03-26T17:51:59.588408Z'
        updated_at:
          description: ISO 8601 timestamp when the room composition was updated.
          type: string
          format: date-time
          example: '2021-03-26T17:51:59.588408Z'
        ended_at:
          description: ISO 8601 timestamp when the room composition has ended.
          type: string
          format: date-time
          example: '2021-03-26T17:51:59.588408Z'
        started_at:
          description: ISO 8601 timestamp when the room composition has stated.
          type: string
          format: date-time
          example: '2021-03-26T17:51:59.588408Z'
        completed_at:
          description: ISO 8601 timestamp when the room composition has completed.
          type: string
          format: date-time
          example: '2021-03-26T17:51:59.588408Z'
        video_layout:
          description: Describes the video layout of the room composition in terms of regions. Limited to 2 regions.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/VideoRegion'
        webhook_event_url:
          description: The URL where webhooks related to this room composition will be sent. Must include a scheme, such as 'https'.
          type: string
          format: uri
          example: https://example.com
        webhook_event_failover_url:
          type: string
          format: uri
          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
          default: ''
        webhook_timeout_secs:
          type: integer
          minimum: 0
          maximum: 30
          description: Specifies how many seconds to wait before timing out a webhook.
          example: 25
          default: null
        resolution:
          type: string
          description: The resolution of the room composition.
          example: 1280x720
        record_type:
          type: string
          example: room_composition
          readOnly: true
      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
    VideoRegion:
      type: object
      properties:
        x_pos:
          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.
          type: integer
          example: 100
          default: 0
        y_pos:
          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.
          type: integer
          example: 100
          default: 0
        z_pos:
          description: Regions with higher z_pos values are stacked on top of regions with lower z_pos values
          type: integer
          minimum: -99
          maximum: 99
          example: 1
          default: 0
        height:
          description: Height of the video region
          type: integer
          minimum: 16
          example: 360
        width:
          description: Width of the video region
          type: integer
          minimum: 16
          example: 480
        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.
          type: integer
          minimum: 1
          maximum: 1000
          example: 3
        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.
          type: integer
          minimum: 1
          maximum: 1000
          example: 3
        video_sources:
          description: Array of video recording ids to be composed in the region. Can be "*" to specify all video recordings in the session
          type: array
          items:
            type: string
            format: uuid
            example: 7b61621f-62e0-4aad-ab11-9fd19e272e73
    billing-group_Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: integer
          format: int32
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          properties: {}
          additionalProperties: true
    video_Error:
      required:
      - code
      - title
      properties:
        code:
          type: string
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          additionalProperties: true
      type: object
    Errors:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/billing-group_Error'
      type: object
    PaginationMeta:
      type: object
      properties:
        total_pages:
          type: integer
          example: 3
        total_results:
          type: integer
          example: 55
        page_number:
          type: integer
          example: 2
        page_size:
          type: integer
          example: 25
    video_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/video_Error'
          type: array
      type: object
    Errors_2:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      type: object
    Error:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: int64
        title:
          type: string
        detail:
          type: string
          description: A human-readable explanation of the error.
        description:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          additionalProperties: true
      example:
        title: Invalid street address
        source:
          pointer: /street_address
        code: '20207'
        description: The street address provided is invalid.
      type: object
  parameters:
    video_PageConsolidated:
      name: page
      in: query
      style: deepObject
      explode: true
      description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
      schema:
        type: object
        properties:
          size:
            type: integer
            minimum: 1
            maximum: 250
            default: 20
            description: The size of the page.
          number:
            type: integer
            minimum: 1
            default: 1
            description: The page number to load.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt