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.