Twilio
Twilio Compositions API

Compose multiple recordings into a single file
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.1
info:
  title: Twilio - Accounts A2p Compositions API
  description: This is the public Twilio REST API.
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.52.0
servers:
- url: https://accounts.twilio.com
tags:
- name: Compositions
  description: Compose multiple recordings into a single file
paths:
  /Compositions:
    get:
      operationId: listCompositions
      summary: Twilio List Compositions
      description: Retrieve a list of compositions. Compositions combine multiple recordings into a single media file.
      tags:
      - Compositions
      parameters:
      - name: Status
        in: query
        schema:
          type: string
          enum:
          - enqueued
          - processing
          - completed
          - deleted
          - failed
      - name: RoomSid
        in: query
        schema:
          type: string
          pattern: ^RM[0-9a-fA-F]{32}$
      - name: PageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: List of compositions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompositionList'
    post:
      operationId: createComposition
      summary: Twilio Create a Composition
      description: Create a new composition from room recordings. Define the layout, resolution, and which audio and video tracks to include.
      tags:
      - Compositions
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateCompositionRequest'
      responses:
        '201':
          description: Composition created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Composition'
        '400':
          description: Invalid request
  /Compositions/{CompositionSid}:
    get:
      operationId: fetchComposition
      summary: Twilio Fetch a Composition
      tags:
      - Compositions
      parameters:
      - name: CompositionSid
        in: path
        required: true
        schema:
          type: string
          pattern: ^CJ[0-9a-fA-F]{32}$
      responses:
        '200':
          description: Composition details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Composition'
        '404':
          description: Composition not found
    delete:
      operationId: deleteComposition
      summary: Twilio Delete a Composition
      tags:
      - Compositions
      parameters:
      - name: CompositionSid
        in: path
        required: true
        schema:
          type: string
          pattern: ^CJ[0-9a-fA-F]{32}$
      responses:
        '204':
          description: Composition deleted
        '404':
          description: Composition not found
  /CompositionSettings/Default:
    get:
      operationId: fetchCompositionSettings
      summary: Twilio Fetch Composition Settings
      tags:
      - Compositions
      responses:
        '200':
          description: Composition settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompositionSettings'
    post:
      operationId: createCompositionSettings
      summary: Twilio Create or Update Composition Settings
      description: Configure the AWS credentials and S3 bucket for storing compositions.
      tags:
      - Compositions
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - FriendlyName
              properties:
                FriendlyName:
                  type: string
                AwsCredentialsSid:
                  type: string
                AwsS3Url:
                  type: string
                  format: uri
                AwsStorageEnabled:
                  type: boolean
                EncryptionKeySid:
                  type: string
                EncryptionEnabled:
                  type: boolean
      responses:
        '201':
          description: Composition settings created
  /v1/Compositions/{Sid}:
    servers:
    - url: https://video.twilio.com
    description: Recording compositions
    x-twilio:
      defaultOutputProperties:
      - sid
      - status
      - resolution
      - format
      pathType: instance
      dependentProperties:
        media:
          mapping:
            composition_sid: sid
          resource_url: /v1None
    get:
      description: Returns a single Composition resource identified by a Composition SID.
      tags:
      - Compositions
      parameters:
      - name: Sid
        in: path
        description: The SID of the Composition resource to fetch.
        schema:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^CJ[0-9a-fA-F]{32}$
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/video.v1.composition'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: FetchComposition
      x-maturity:
      - GA
    delete:
      description: Delete a Recording Composition resource identified by a Composition SID.
      tags:
      - Compositions
      parameters:
      - name: Sid
        in: path
        description: The SID of the Composition resource to delete.
        schema:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^CJ[0-9a-fA-F]{32}$
        required: true
      responses:
        '204':
          description: The resource was deleted successfully.
      security:
      - accountSid_authToken: []
      operationId: DeleteComposition
      x-maturity:
      - GA
  /v1/Compositions:
    servers:
    - url: https://video.twilio.com
    description: Recording compositions
    x-twilio:
      defaultOutputProperties:
      - sid
      - status
      - resolution
      - format
      pathType: list
      dependentProperties:
        media:
          mapping:
            composition_sid: sid
          resource_url: /v1None
    get:
      description: List of all Recording compositions.
      tags:
      - Compositions
      parameters:
      - name: Status
        in: query
        description: 'Read only Composition resources with this status. Can be: `enqueued`, `processing`, `completed`, `deleted`, or `failed`.'
        schema:
          type: string
          $ref: '#/components/schemas/composition_enum_status'
      - name: DateCreatedAfter
        in: query
        description: Read only Composition resources created on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date-time with time zone.
        schema:
          type: string
          format: date-time
      - name: DateCreatedBefore
        in: query
        description: Read only Composition resources created before this ISO 8601 date-time with time zone.
        schema:
          type: string
          format: date-time
      - name: RoomSid
        in: query
        description: Read only Composition resources with this Room SID.
        schema:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^RM[0-9a-fA-F]{32}$
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCompositionResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListComposition
      x-maturity:
      - GA
    post:
      description: ''
      tags:
      - Compositions
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/video.v1.composition'
          description: Created
      security:
      - accountSid_authToken: []
      operationId: CreateComposition
      x-maturity:
      - GA
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateCompositionRequest_2'
components:
  schemas:
    composition_enum_status:
      type: string
      enum:
      - enqueued
      - processing
      - completed
      - deleted
      - failed
    composition_enum_format:
      type: string
      enum:
      - mp4
      - webm
    video.v1.composition:
      type: object
      properties:
        account_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created the Composition resource.
        status:
          type: string
          $ref: '#/components/schemas/composition_enum_status'
          nullable: true
          description: 'The status of the composition. Can be: `enqueued`, `processing`, `completed`, `deleted` or `failed`. `enqueued` is the initial state and indicates that the composition request has been received and is scheduled for processing; `processing` indicates the composition is being processed; `completed` indicates the composition has been completed and is available for download; `deleted` means the composition media has been deleted from the system, but its metadata is still available for 30 days; `failed` indicates the composition failed to execute the media processing task.'
        date_created:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        date_completed:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the composition's media processing task finished, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        date_deleted:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the composition generated media was deleted, specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^CJ[0-9a-fA-F]{32}$
          nullable: true
          description: The unique string that we created to identify the Composition resource.
        room_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^RM[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the Group Room that generated the audio and video tracks used in the composition. All media sources included in a composition must belong to the same Group Room.
        audio_sources:
          type: array
          items:
            type: string
          nullable: true
          description: The array of track names to include in the composition. The composition includes all audio sources specified in `audio_sources` except those specified in `audio_sources_excluded`. The track names in this property can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, `student*` includes tracks named `student` as well as `studentTeam`.
          x-twilio:
            pii:
              handling: standard
              deleteSla: 30
        audio_sources_excluded:
          type: array
          items:
            type: string
          nullable: true
          description: The array of track names to exclude from the composition. The composition includes all audio sources specified in `audio_sources` except for those specified in `audio_sources_excluded`. The track names in this property can include an asterisk as a wild card character, which matches zero or more characters in a track name. For example, `student*` excludes `student` as well as `studentTeam`. This parameter can also be empty.
          x-twilio:
            pii:
              handling: standard
              deleteSla: 30
        video_layout:
          nullable: true
          description: An object that describes the video layout of the composition in terms of regions. See [Specifying Video Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts) for more info.
          x-twilio:
            pii:
              handling: standard
              deleteSla: 30
        resolution:
          type: string
          nullable: true
          description: The dimensions of the video image in pixels expressed as columns (width) and rows (height). The string's format is `{width}x{height}`, such as `640x480`.
        trim:
          type: boolean
          nullable: true
          description: Whether to remove intervals with no media, as specified in the POST request that created the composition. Compositions with `trim` enabled are shorter when the Room is created and no Participant joins for a while as well as if all the Participants leave the room and join later, because those gaps will be removed. See [Specifying Video Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts) for more info.
        format:
          type: string
          $ref: '#/components/schemas/composition_enum_format'
          nullable: true
          description: The container format of the composition's media files as specified in the POST request that created the Composition resource. See [POST Parameters](https://www.twilio.com/docs/video/api/compositions-resource#http-post-parameters) for more information.
        bitrate:
          type: integer
          nullable: true
          description: The average bit rate of the composition's media.
        size:
          type: integer
          format: int64
          nullable: true
          description: The size of the composed media file in bytes.
        duration:
          type: integer
          nullable: true
          description: The duration of the composition's media file in seconds.
        media_external_location:
          type: string
          format: uri
          nullable: true
          description: The URL of the media file associated with the composition when stored externally. See [External S3 Compositions](/docs/video/api/external-s3-compositions) for more details.
        status_callback:
          type: string
          format: uri
          nullable: true
          description: The URL called using the `status_callback_method` to send status information on every composition event.
        status_callback_method:
          type: string
          format: http-method
          enum:
          - HEAD
          - GET
          - POST
          - PATCH
          - PUT
          - DELETE
          nullable: true
          description: 'The HTTP method used to call `status_callback`. Can be: `POST` or `GET`, defaults to `POST`.'
        url:
          type: string
          format: uri
          nullable: true
          description: The absolute URL of the resource.
        links:
          type: object
          format: uri-map
          nullable: true
          description: The URL of the media file associated with the composition.
    CompositionList:
      type: object
      properties:
        compositions:
          type: array
          items:
            $ref: '#/components/schemas/Composition'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        first_page_url:
          type: string
          format: uri
        previous_page_url:
          type: string
          format: uri
        next_page_url:
          type: string
          format: uri
        url:
          type: string
          format: uri
        key:
          type: string
    CreateCompositionRequest_2:
      type: object
      required:
      - RoomSid
      properties:
        RoomSid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^RM[0-9a-fA-F]{32}$
          description: The SID of the Group Room with the media tracks to be used as composition sources.
        VideoLayout:
          description: An object that describes the video layout of the composition in terms of regions. See [Specifying Video Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts) for more info. Please, be aware that either video_layout or audio_sources have to be provided to get a valid creation request
        AudioSources:
          type: array
          items:
            type: string
          description: An array of track names from the same group room to merge into the new composition. Can include zero or more track names. The new composition includes all audio sources specified in `audio_sources` except for those specified in `audio_sources_excluded`. The track names in this parameter can include an asterisk as a wild card character, which will match zero or more characters in a track name. For example, `student*` includes `student` as well as `studentTeam`. Please, be aware that either video_layout or audio_sources have to be provided to get a valid creation request
        AudioSourcesExcluded:
          type: array
          items:
            type: string
          description: An array of track names to exclude. The new composition includes all audio sources specified in `audio_sources` except for those specified in `audio_sources_excluded`. The track names in this parameter can include an asterisk as a wild card character, which will match zero or more characters in a track name. For example, `student*` excludes `student` as well as `studentTeam`. This parameter can also be empty.
        Resolution:
          type: string
          description: "A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to `640x480`. \nThe string's format is `{width}x{height}` where: \n\n* 16 <= `{width}` <= 1280\n* 16 <= `{height}` <= 1280\n* `{width}` * `{height}` <= 921,600\n\nTypical values are: \n\n* HD = `1280x720`\n* PAL = `1024x576`\n* VGA = `640x480`\n* CIF = `320x240`\n\nNote that the `resolution` imposes an aspect ratio to the resulting composition. When the original video tracks are constrained by the aspect ratio, they are scaled to fit. See [Specifying Video Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts) for more info."
        Format:
          type: string
          $ref: '#/components/schemas/composition_enum_format'
          description: 'The container format of the composition''s media files. Can be: `mp4` or `webm` and the default is `webm`. If you specify `mp4` or `webm`, you must also specify one or more `audio_sources` and/or a `video_layout` element that contains a valid `video_sources` list, otherwise an error occurs.'
        StatusCallback:
          type: string
          format: uri
          description: The URL we should call using the `status_callback_method` to send status information to your application on every composition event. If not provided, status callback events will not be dispatched.
        StatusCallbackMethod:
          type: string
          format: http-method
          enum:
          - HEAD
          - GET
          - POST
          - PATCH
          - PUT
          - DELETE
          description: 'The HTTP method we should use to call `status_callback`. Can be: `POST` or `GET` and the default is `POST`.'
        Trim:
          type: boolean
          description: Whether to clip the intervals where there is no active media in the composition. The default is `true`. Compositions with `trim` enabled are shorter when the Room is created and no Participant joins for a while as well as if all the Participants leave the room and join later, because those gaps will be removed. See [Specifying Video Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts) for more info.
    CompositionSettings:
      type: object
      properties:
        account_sid:
          type: string
          pattern: ^AC[0-9a-fA-F]{32}$
        friendly_name:
          type: string
        aws_credentials_sid:
          type: string
        aws_s3_url:
          type: string
          format: uri
        aws_storage_enabled:
          type: boolean
        encryption_key_sid:
          type: string
        encryption_enabled:
          type: boolean
        url:
          type: string
          format: uri
    ListCompositionResponse:
      type: object
      properties:
        compositions:
          type: array
          items:
            $ref: '#/components/schemas/video.v1.composition'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type: string
              format: uri
              nullable: true
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type: string
              format: uri
              nullable: true
            url:
              type: string
              format: uri
            key:
              type: string
    Composition:
      type: object
      properties:
        sid:
          type: string
          pattern: ^CJ[0-9a-fA-F]{32}$
          description: Unique identifier for the composition
        account_sid:
          type: string
          pattern: ^AC[0-9a-fA-F]{32}$
        room_sid:
          type: string
          pattern: ^RM[0-9a-fA-F]{32}$
        status:
          type: string
          enum:
          - enqueued
          - processing
          - completed
          - deleted
          - failed
        resolution:
          type: string
          description: Resolution in WxH format
        format:
          type: string
          enum:
          - mp4
          - webm
        bitrate:
          type: integer
        duration:
          type: integer
          description: Duration in seconds
        size:
          type: integer
          description: Size in bytes
        trim:
          type: boolean
        audio_sources:
          type: array
          items:
            type: string
        audio_sources_excluded:
          type: array
          items:
            type: string
        video_layout:
          type: object
        media_external_location:
          type: string
          format: uri
        date_created:
          type: string
          format: date-time
        date_completed:
          type: string
          format: date-time
        date_deleted:
          type: string
          format: date-time
        url:
          type: string
          format: uri
        links:
          type: object
          properties:
            media:
              type: string
              format: uri
    CreateCompositionRequest:
      type: object
      required:
      - RoomSid
      properties:
        RoomSid:
          type: string
          description: SID of the room to compose
          pattern: ^RM[0-9a-fA-F]{32}$
        VideoLayout:
          type: string
          description: JSON object defining the video layout
        AudioSources:
          type: array
          items:
            type: string
        AudioSourcesExcluded:
          type: array
          items:
            type: string
        Resolution:
          type: string
          description: Resolution in WxH format (e.g., 1280x720)
        Format:
          type: string
          enum:
          - mp4
          - webm
          default: webm
        Trim:
          type: boolean
          default: true
        StatusCallback:
          type: string
          format: uri
        StatusCallbackMethod:
          type: string
          enum:
          - GET
          - POST
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
x-maturity:
- name: GA
  description: This product is Generally Available.
- name: Beta
  description: PLEASE NOTE that this is a Beta product that is subject to change. Use it with caution.
Twilio Compositions API

Documentation

Specifications

Other Resources

OpenAPI Specification
