Twilio - Video
1.29.1

Base URL 
https://video.twilio.com


⚠️ This is an unofficial public Twilio REST API documentation generated from an OpenAPI contract.

The source file was taken from https://github.com/twilio/twilio-oai/blob/main/spec/json/twilio_video_v1.json as a demonstration of the Bump.sh product.

This is the public Twilio REST API.

This is version 1.29.1 of this API documentation. Last update on May 24, 2022.

This API is provided under license Apache 2.0.

Authentication

Account sid auth token (http)

Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password (separated by a : colon).

Example: send a Authorization: Basic aGVsbG86aGVsbG8= HTTP header with your requests to authenticate with the API.

Composition hooks

List of all Recording CompositionHook resources

GET /v1/CompositionHooks

Recording composition hooks

List of all Recording CompositionHook resources.

Query parameters

  • Enabled boolean

    Read only CompositionHook resources with an enabled value that matches this parameter.

  • DateCreatedAfter string(date-time)

    Read only CompositionHook resources created on or after this ISO 8601 datetime with time zone.

  • DateCreatedBefore string(date-time)

    Read only CompositionHook resources created before this ISO 8601 datetime with time zone.

  • FriendlyName string

    Read only CompositionHook resources with friendly names that match this string. The match is not case sensitive and can include asterisk * characters as wildcard match.

  • PageSize integer

    How many resources to return in each list page. The default is 50, and the maximum is 1000.

    Minimum value is 1, maximum value is 1000.

Responses

  • 200

    OK

    Hide response attributes Show response attributes object
    • composition_hooks array[object]
      Hide composition_hooks attributes Show composition_hooks attributes array[object]
      • account_sid string | null

        The SID of the Account that created the resource

        Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

      • audio_sources array[string] | null

        The array of track names to include in the compositions created by the composition hook

      • audio_sources_excluded array[string] | null

        The array of track names to exclude from the compositions created by the composition hook

      • date_created string(date-time) | null

        The ISO 8601 date and time in GMT when the resource was created

      • date_updated string(date-time) | null

        The ISO 8601 date and time in GMT when the resource was last updated

      • enabled boolean | null

        Whether the CompositionHook is active

      • format string | null

        The container format of the media files used by the compositions created by the composition hook

        Values are mp4 or webm.

      • friendly_name string | null

        The string that you assigned to describe the resource

      • resolution string | null

        The dimensions of the video image in pixels expressed as columns (width) and rows (height)

      • sid string | null

        The unique string that identifies the resource

        Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HK[0-9a-fA-F]{32}$.

      • status_callback string(uri) | null

        The URL to send status information to your application

      • status_callback_method string(http-method) | null

        The HTTP method we should use to call status_callback

        Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

      • trim boolean | null

        Whether intervals with no media are clipped

      • url string(uri) | null

        The absolute URL of the resource

      • video_layout

        A JSON object that describes the video layout of the Composition

    • meta object
      Hide meta attributes Show meta attributes object
GET /v1/CompositionHooks 
curl \
 -X GET https://video.twilio.com/v1/CompositionHooks \
 --user "username:password"
Response examples (200) 
{
  "composition_hooks": [
    {
      "account_sid": "string",
      "audio_sources": [
        "string"
      ],
      "audio_sources_excluded": [
        "string"
      ],
      "date_created": "2023-05-04T09:42:00+00:00",
      "date_updated": "2023-05-04T09:42:00+00:00",
      "enabled": true,
      "format": "mp4",
      "friendly_name": "string",
      "resolution": "string",
      "sid": "string",
      "status_callback": "https://example.com",
      "status_callback_method": "HEAD",
      "trim": true,
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}
Response examples (200) 
{
  "composition_hooks": [
    {
      "account_sid": "string",
      "audio_sources": [
        "string"
      ],
      "audio_sources_excluded": [
        "string"
      ],
      "date_created": "2025-05-04T09:42:00Z",
      "date_updated": "2025-05-04T09:42:00Z",
      "enabled": true,
      "format": "mp4",
      "friendly_name": "string",
      "resolution": "string",
      "sid": "string",
      "status_callback": "https://example.com",
      "status_callback_method": "HEAD",
      "trim": true,
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Create composition hook

POST /v1/CompositionHooks

Recording composition hooks

Body

  • AudioSources array[string]

    An array of track names from the same group room to merge into the compositions created by the composition hook. Can include zero or more track names. A composition triggered by the composition hook includes all audio sources specified in audio_sources except those specified in audio_sources_excluded. The track names in this parameter 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.

  • AudioSourcesExcluded array[string]

    An array of track names to exclude. A composition triggered by the composition hook 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 matches zero or more characters in a track name. For example, student* excludes student as well as studentTeam. This parameter can also be empty.

  • Enabled boolean

    Whether the composition hook is active. When true, the composition hook will be triggered for every completed Group Room in the account. When false, the composition hook will never be triggered.

  • Format string

    The container format of the media files used by the compositions created by the composition hook. Can be: mp4 or webm and the default is webm. If mp4 or webm, audio_sources must have one or more tracks and/or a video_layout element must contain a valid video_sources list, otherwise an error occurs.

    Values are mp4 or webm.

  • FriendlyName string Required

    A descriptive string that you create to describe the resource. It can be up to 100 characters long and it must be unique within the account.

  • Resolution string

    A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to 640x480. The string's format is {width}x{height} where:

    • 16 <= {width} <= 1280
    • 16 <= {height} <= 1280
    • {width} * {height} <= 921,600

    Typical values are:

    • HD = 1280x720
    • PAL = 1024x576
    • VGA = 640x480
    • CIF = 320x240

    Note 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 for more info.

  • StatusCallback string(uri)

    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 string(http-method)

    The HTTP method we should use to call status_callback. Can be: POST or GET and the default is POST.

    Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

  • Trim boolean

    Whether to clip the intervals where there is no active media in the Compositions triggered by the composition hook. 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 for more info.

  • VideoLayout

    An object that describes the video layout of the composition hook in terms of regions. See Specifying Video Layouts for more info.

Responses

  • 201

    Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • audio_sources array[string] | null

      The array of track names to include in the compositions created by the composition hook

    • audio_sources_excluded array[string] | null

      The array of track names to exclude from the compositions created by the composition hook

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_updated string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was last updated

    • enabled boolean | null

      Whether the CompositionHook is active

    • format string | null

      The container format of the media files used by the compositions created by the composition hook

      Values are mp4 or webm.

    • friendly_name string | null

      The string that you assigned to describe the resource

    • resolution string | null

      The dimensions of the video image in pixels expressed as columns (width) and rows (height)

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HK[0-9a-fA-F]{32}$.

    • status_callback string(uri) | null

      The URL to send status information to your application

    • status_callback_method string(http-method) | null

      The HTTP method we should use to call status_callback

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • trim boolean | null

      Whether intervals with no media are clipped

    • url string(uri) | null

      The absolute URL of the resource

    • video_layout

      A JSON object that describes the video layout of the Composition
POST /v1/CompositionHooks 
curl \
 -X POST https://video.twilio.com/v1/CompositionHooks \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AudioSources=string&AudioSourcesExcluded=string&Enabled=true&Format=mp4&FriendlyName=string&Resolution=string&StatusCallback=https%3A%2F%2Fexample.com&StatusCallbackMethod=HEAD&Trim=true'
Request example 
{
  "AudioSources": [
    "string"
  ],
  "AudioSourcesExcluded": [
    "string"
  ],
  "Enabled": true,
  "Format": "mp4",
  "FriendlyName": "string",
  "Resolution": "string",
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Trim": true
}
Request examples 
{
  "AudioSources": [
    "string"
  ],
  "AudioSourcesExcluded": [
    "string"
  ],
  "Enabled": true,
  "Format": "mp4",
  "FriendlyName": "string",
  "Resolution": "string",
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Trim": true
}
Response examples (201) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "enabled": true,
  "format": "mp4",
  "friendly_name": "string",
  "resolution": "string",
  "sid": "string",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}
Response examples (201) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "date_created": "2025-05-04T09:42:00Z",
  "date_updated": "2025-05-04T09:42:00Z",
  "enabled": true,
  "format": "mp4",
  "friendly_name": "string",
  "resolution": "string",
  "sid": "string",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}

Returns a single CompositionHook resource identified by a CompositionHook SID

GET /v1/CompositionHooks/{Sid}

Recording composition hooks

Returns a single CompositionHook resource identified by a CompositionHook SID.

Path parameters

  • Sid string Required

    The SID of the CompositionHook resource to fetch.

Responses

  • 200

    OK

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • audio_sources array[string] | null

      The array of track names to include in the compositions created by the composition hook

    • audio_sources_excluded array[string] | null

      The array of track names to exclude from the compositions created by the composition hook

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_updated string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was last updated

    • enabled boolean | null

      Whether the CompositionHook is active

    • format string | null

      The container format of the media files used by the compositions created by the composition hook

      Values are mp4 or webm.

    • friendly_name string | null

      The string that you assigned to describe the resource

    • resolution string | null

      The dimensions of the video image in pixels expressed as columns (width) and rows (height)

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HK[0-9a-fA-F]{32}$.

    • status_callback string(uri) | null

      The URL to send status information to your application

    • status_callback_method string(http-method) | null

      The HTTP method we should use to call status_callback

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • trim boolean | null

      Whether intervals with no media are clipped

    • url string(uri) | null

      The absolute URL of the resource

    • video_layout

      A JSON object that describes the video layout of the Composition
GET /v1/CompositionHooks/{Sid} 
curl \
 -X GET https://video.twilio.com/v1/CompositionHooks/{Sid} \
 --user "username:password"
Response examples (200) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "enabled": true,
  "format": "mp4",
  "friendly_name": "string",
  "resolution": "string",
  "sid": "string",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}
Response examples (200) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "date_created": "2025-05-04T09:42:00Z",
  "date_updated": "2025-05-04T09:42:00Z",
  "enabled": true,
  "format": "mp4",
  "friendly_name": "string",
  "resolution": "string",
  "sid": "string",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}

Update composition hook

POST /v1/CompositionHooks/{Sid}

Recording composition hooks

Path parameters

  • Sid string Required

    The SID of the CompositionHook resource to update.

Body

  • AudioSources array[string]

    An array of track names from the same group room to merge into the compositions created by the composition hook. Can include zero or more track names. A composition triggered by the composition hook includes all audio sources specified in audio_sources except those specified in audio_sources_excluded. The track names in this parameter 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.

  • AudioSourcesExcluded array[string]

    An array of track names to exclude. A composition triggered by the composition hook 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 matches zero or more characters in a track name. For example, student* excludes student as well as studentTeam. This parameter can also be empty.

  • Enabled boolean

    Whether the composition hook is active. When true, the composition hook will be triggered for every completed Group Room in the account. When false, the composition hook never triggers.

  • Format string

    The container format of the media files used by the compositions created by the composition hook. Can be: mp4 or webm and the default is webm. If mp4 or webm, audio_sources must have one or more tracks and/or a video_layout element must contain a valid video_sources list, otherwise an error occurs.

    Values are mp4 or webm.

  • FriendlyName string Required

    A descriptive string that you create to describe the resource. It can be up to 100 characters long and it must be unique within the account.

  • Resolution string

    A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to 640x480. The string's format is {width}x{height} where:

    • 16 <= {width} <= 1280
    • 16 <= {height} <= 1280
    • {width} * {height} <= 921,600

    Typical values are:

    • HD = 1280x720
    • PAL = 1024x576
    • VGA = 640x480
    • CIF = 320x240

    Note 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 for more info.

  • StatusCallback string(uri)

    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 string(http-method)

    The HTTP method we should use to call status_callback. Can be: POST or GET and the default is POST.

    Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

  • Trim boolean

    Whether to clip the intervals where there is no active media in the compositions triggered by the composition hook. 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 for more info.

  • VideoLayout

    A JSON object that describes the video layout of the composition hook in terms of regions. See Specifying Video Layouts for more info.

Responses

  • 200

    OK

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • audio_sources array[string] | null

      The array of track names to include in the compositions created by the composition hook

    • audio_sources_excluded array[string] | null

      The array of track names to exclude from the compositions created by the composition hook

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_updated string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was last updated

    • enabled boolean | null

      Whether the CompositionHook is active

    • format string | null

      The container format of the media files used by the compositions created by the composition hook

      Values are mp4 or webm.

    • friendly_name string | null

      The string that you assigned to describe the resource

    • resolution string | null

      The dimensions of the video image in pixels expressed as columns (width) and rows (height)

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HK[0-9a-fA-F]{32}$.

    • status_callback string(uri) | null

      The URL to send status information to your application

    • status_callback_method string(http-method) | null

      The HTTP method we should use to call status_callback

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • trim boolean | null

      Whether intervals with no media are clipped

    • url string(uri) | null

      The absolute URL of the resource

    • video_layout

      A JSON object that describes the video layout of the Composition
POST /v1/CompositionHooks/{Sid} 
curl \
 -X POST https://video.twilio.com/v1/CompositionHooks/{Sid} \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AudioSources=string&AudioSourcesExcluded=string&Enabled=true&Format=mp4&FriendlyName=string&Resolution=string&StatusCallback=https%3A%2F%2Fexample.com&StatusCallbackMethod=HEAD&Trim=true'
Request example 
{
  "AudioSources": [
    "string"
  ],
  "AudioSourcesExcluded": [
    "string"
  ],
  "Enabled": true,
  "Format": "mp4",
  "FriendlyName": "string",
  "Resolution": "string",
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Trim": true
}
Request examples 
{
  "AudioSources": [
    "string"
  ],
  "AudioSourcesExcluded": [
    "string"
  ],
  "Enabled": true,
  "Format": "mp4",
  "FriendlyName": "string",
  "Resolution": "string",
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Trim": true
}
Response examples (200) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "enabled": true,
  "format": "mp4",
  "friendly_name": "string",
  "resolution": "string",
  "sid": "string",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}
Response examples (200) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "date_created": "2025-05-04T09:42:00Z",
  "date_updated": "2025-05-04T09:42:00Z",
  "enabled": true,
  "format": "mp4",
  "friendly_name": "string",
  "resolution": "string",
  "sid": "string",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}

Delete a Recording CompositionHook resource identified by a `CompositionHook SID`

DELETE /v1/CompositionHooks/{Sid}

Recording composition hooks

Delete a Recording CompositionHook resource identified by a CompositionHook SID.

Path parameters

  • Sid string Required

    The SID of the CompositionHook resource to delete.

Responses

  • 204

    The resource was deleted successfully.

DELETE /v1/CompositionHooks/{Sid} 
curl \
 -X DELETE https://video.twilio.com/v1/CompositionHooks/{Sid} \
 --user "username:password"

Composition settings

Fetch composition settings

GET /v1/CompositionSettings/Default

Recording composition settings

Responses

  • 200

    OK

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • aws_credentials_sid string | null

      The SID of the stored Credential resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CR[0-9a-fA-F]{32}$.

    • aws_s3_url string(uri) | null

      The URL of the AWS S3 bucket where the compositions are stored

    • aws_storage_enabled boolean | null

      Whether all compositions are written to the aws_s3_url

    • encryption_enabled boolean | null

      Whether all compositions are stored in an encrypted form

    • encryption_key_sid string | null

      The SID of the Public Key resource used for encryption

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CR[0-9a-fA-F]{32}$.

    • friendly_name string | null

      The string that you assigned to describe the resource

    • url string(uri) | null

      The absolute URL of the resource
GET /v1/CompositionSettings/Default 
curl \
 -X GET https://video.twilio.com/v1/CompositionSettings/Default \
 --user "username:password"
Response examples (200) 
{
  "account_sid": "string",
  "aws_credentials_sid": "string",
  "aws_s3_url": "https://example.com",
  "aws_storage_enabled": true,
  "encryption_enabled": true,
  "encryption_key_sid": "string",
  "friendly_name": "string",
  "url": "https://example.com"
}
Response examples (200) 
{
  "account_sid": "string",
  "aws_credentials_sid": "string",
  "aws_s3_url": "https://example.com",
  "aws_storage_enabled": true,
  "encryption_enabled": true,
  "encryption_key_sid": "string",
  "friendly_name": "string",
  "url": "https://example.com"
}

Create composition settings

POST /v1/CompositionSettings/Default

Recording composition settings

Body

  • AwsCredentialsSid string

    The SID of the stored Credential resource.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CR[0-9a-fA-F]{32}$.

  • AwsS3Url string(uri)

    The URL of the AWS S3 bucket where the compositions should be stored. We only support DNS-compliant URLs like https://documentation-example-twilio-bucket/compositions, where compositions is the path in which you want the compositions to be stored. This URL accepts only URI-valid characters, as described in the RFC 3986.

  • AwsStorageEnabled boolean

    Whether all compositions should be written to the aws_s3_url. When false, all compositions are stored in our cloud.

  • EncryptionEnabled boolean

    Whether all compositions should be stored in an encrypted form. The default is false.

  • EncryptionKeySid string

    The SID of the Public Key resource to use for encryption.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CR[0-9a-fA-F]{32}$.

  • FriendlyName string Required

    A descriptive string that you create to describe the resource and show to the user in the console

Responses

  • 201

    Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • aws_credentials_sid string | null

      The SID of the stored Credential resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CR[0-9a-fA-F]{32}$.

    • aws_s3_url string(uri) | null

      The URL of the AWS S3 bucket where the compositions are stored

    • aws_storage_enabled boolean | null

      Whether all compositions are written to the aws_s3_url

    • encryption_enabled boolean | null

      Whether all compositions are stored in an encrypted form

    • encryption_key_sid string | null

      The SID of the Public Key resource used for encryption

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CR[0-9a-fA-F]{32}$.

    • friendly_name string | null

      The string that you assigned to describe the resource

    • url string(uri) | null

      The absolute URL of the resource
POST /v1/CompositionSettings/Default 
curl \
 -X POST https://video.twilio.com/v1/CompositionSettings/Default \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AwsCredentialsSid=string&AwsS3Url=https%3A%2F%2Fexample.com&AwsStorageEnabled=true&EncryptionEnabled=true&EncryptionKeySid=string&FriendlyName=string'
Request example 
{
  "AwsCredentialsSid": "string",
  "AwsS3Url": "https://example.com",
  "AwsStorageEnabled": true,
  "EncryptionEnabled": true,
  "EncryptionKeySid": "string",
  "FriendlyName": "string"
}
Request examples 
{
  "AwsCredentialsSid": "string",
  "AwsS3Url": "https://example.com",
  "AwsStorageEnabled": true,
  "EncryptionEnabled": true,
  "EncryptionKeySid": "string",
  "FriendlyName": "string"
}
Response examples (201) 
{
  "account_sid": "string",
  "aws_credentials_sid": "string",
  "aws_s3_url": "https://example.com",
  "aws_storage_enabled": true,
  "encryption_enabled": true,
  "encryption_key_sid": "string",
  "friendly_name": "string",
  "url": "https://example.com"
}
Response examples (201) 
{
  "account_sid": "string",
  "aws_credentials_sid": "string",
  "aws_s3_url": "https://example.com",
  "aws_storage_enabled": true,
  "encryption_enabled": true,
  "encryption_key_sid": "string",
  "friendly_name": "string",
  "url": "https://example.com"
}

Compositions

List of all Recording compositions

GET /v1/Compositions

Recording compositions

List of all Recording compositions.

Query parameters

  • Status string

    Read only Composition resources with this status. Can be: enqueued, processing, completed, deleted, or failed.

    Values are enqueued, processing, completed, deleted, or failed.

  • DateCreatedAfter string(date-time)

    Read only Composition resources created on or after this ISO 8601 date-time with time zone.

  • DateCreatedBefore string(date-time)

    Read only Composition resources created before this ISO 8601 date-time with time zone.

  • RoomSid string

    Read only Composition resources with this Room SID.

  • PageSize integer

    How many resources to return in each list page. The default is 50, and the maximum is 1000.

    Minimum value is 1, maximum value is 1000.

Responses

  • 200

    OK

    Hide response attributes Show response attributes object
    • compositions array[object]
      Hide compositions attributes Show compositions attributes array[object]
      • account_sid string | null

        The SID of the Account that created the resource

        Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

      • audio_sources array[string] | null

        The array of track names to include in the composition

      • audio_sources_excluded array[string] | null

        The array of track names to exclude from the composition

      • bitrate integer | null

        The average bit rate of the composition's media

      • date_completed string(date-time) | null

        Date when the media processing task finished

      • date_created string(date-time) | null

        The ISO 8601 date and time in GMT when the resource was created

      • date_deleted string(date-time) | null

        The ISO 8601 date and time in GMT when the composition generated media was deleted

      • duration integer | null

        The duration of the composition's media file in seconds

      • format string | null

        The container format of the composition's media files as specified in the POST request that created the Composition resource

        Values are mp4 or webm.

      • links object(uri-map) | null

        The URL of the media file associated with the composition

      • media_external_location string(uri) | null

        The URL of the media file associated with the composition when stored externally

      • resolution string | null

        The dimensions of the video image in pixels expressed as columns (width) and rows (height)

      • room_sid string | null

        The SID of the Group Room that generated the audio and video tracks used in the composition

        Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RM[0-9a-fA-F]{32}$.

      • sid string | null

        The unique string that identifies the resource

        Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CJ[0-9a-fA-F]{32}$.

      • size integer | null

        The size of the composed media file in bytes

      • status string | null

        The status of the composition

        Values are enqueued, processing, completed, deleted, or failed.

      • status_callback string(uri) | null

        The URL called to send status information on every composition event.

      • status_callback_method string(http-method) | null

        The HTTP method used to call status_callback

        Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

      • trim boolean | null

        Whether to remove intervals with no media

      • url string(uri) | null

        The absolute URL of the resource

      • video_layout

        An object that describes the video layout of the composition

    • meta object
      Hide meta attributes Show meta attributes object
GET /v1/Compositions 
curl \
 -X GET https://video.twilio.com/v1/Compositions \
 --user "username:password"
Response examples (200) 
{
  "compositions": [
    {
      "account_sid": "string",
      "audio_sources": [
        "string"
      ],
      "audio_sources_excluded": [
        "string"
      ],
      "bitrate": 42,
      "date_completed": "2023-05-04T09:42:00+00:00",
      "date_created": "2023-05-04T09:42:00+00:00",
      "date_deleted": "2023-05-04T09:42:00+00:00",
      "duration": 42,
      "format": "mp4",
      "links": {},
      "media_external_location": "https://example.com",
      "resolution": "string",
      "room_sid": "string",
      "sid": "string",
      "size": 42,
      "status": "enqueued",
      "status_callback": "https://example.com",
      "status_callback_method": "HEAD",
      "trim": true,
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}
Response examples (200) 
{
  "compositions": [
    {
      "account_sid": "string",
      "audio_sources": [
        "string"
      ],
      "audio_sources_excluded": [
        "string"
      ],
      "bitrate": 42,
      "date_completed": "2025-05-04T09:42:00Z",
      "date_created": "2025-05-04T09:42:00Z",
      "date_deleted": "2025-05-04T09:42:00Z",
      "duration": 42,
      "format": "mp4",
      "links": {},
      "media_external_location": "https://example.com",
      "resolution": "string",
      "room_sid": "string",
      "sid": "string",
      "size": 42,
      "status": "enqueued",
      "status_callback": "https://example.com",
      "status_callback_method": "HEAD",
      "trim": true,
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Create composition

POST /v1/Compositions

Recording compositions

Body

  • AudioSources array[string]

    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 array[string]

    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.

  • Format string

    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.

    Values are mp4 or webm.

  • Resolution string

    A string that describes the columns (width) and rows (height) of the generated composed video in pixels. Defaults to 640x480. The string's format is {width}x{height} where:

    • 16 <= {width} <= 1280
    • 16 <= {height} <= 1280
    • {width} * {height} <= 921,600

    Typical values are:

    • HD = 1280x720
    • PAL = 1024x576
    • VGA = 640x480
    • CIF = 320x240

    Note 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 for more info.

  • RoomSid string Required

    The SID of the Group Room with the media tracks to be used as composition sources.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RM[0-9a-fA-F]{32}$.

  • StatusCallback string(uri)

    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 string(http-method)

    The HTTP method we should use to call status_callback. Can be: POST or GET and the default is POST.

    Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

  • Trim boolean

    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 for more info.

  • VideoLayout

    An object that describes the video layout of the composition in terms of regions. See 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

Responses

  • 201

    Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • audio_sources array[string] | null

      The array of track names to include in the composition

    • audio_sources_excluded array[string] | null

      The array of track names to exclude from the composition

    • bitrate integer | null

      The average bit rate of the composition's media

    • date_completed string(date-time) | null

      Date when the media processing task finished

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_deleted string(date-time) | null

      The ISO 8601 date and time in GMT when the composition generated media was deleted

    • duration integer | null

      The duration of the composition's media file in seconds

    • format string | null

      The container format of the composition's media files as specified in the POST request that created the Composition resource

      Values are mp4 or webm.

    • links object(uri-map) | null

      The URL of the media file associated with the composition

    • media_external_location string(uri) | null

      The URL of the media file associated with the composition when stored externally

    • resolution string | null

      The dimensions of the video image in pixels expressed as columns (width) and rows (height)

    • room_sid string | null

      The SID of the Group Room that generated the audio and video tracks used in the composition

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RM[0-9a-fA-F]{32}$.

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CJ[0-9a-fA-F]{32}$.

    • size integer | null

      The size of the composed media file in bytes

    • status string | null

      The status of the composition

      Values are enqueued, processing, completed, deleted, or failed.

    • status_callback string(uri) | null

      The URL called to send status information on every composition event.

    • status_callback_method string(http-method) | null

      The HTTP method used to call status_callback

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • trim boolean | null

      Whether to remove intervals with no media

    • url string(uri) | null

      The absolute URL of the resource

    • video_layout

      An object that describes the video layout of the composition
POST /v1/Compositions 
curl \
 -X POST https://video.twilio.com/v1/Compositions \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AudioSources=string&AudioSourcesExcluded=string&Format=mp4&Resolution=string&RoomSid=string&StatusCallback=https%3A%2F%2Fexample.com&StatusCallbackMethod=HEAD&Trim=true'
Request example 
{
  "AudioSources": [
    "string"
  ],
  "AudioSourcesExcluded": [
    "string"
  ],
  "Format": "mp4",
  "Resolution": "string",
  "RoomSid": "string",
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Trim": true
}
Request examples 
{
  "AudioSources": [
    "string"
  ],
  "AudioSourcesExcluded": [
    "string"
  ],
  "Format": "mp4",
  "Resolution": "string",
  "RoomSid": "string",
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Trim": true
}
Response examples (201) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "bitrate": 42,
  "date_completed": "2023-05-04T09:42:00+00:00",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_deleted": "2023-05-04T09:42:00+00:00",
  "duration": 42,
  "format": "mp4",
  "links": {},
  "media_external_location": "https://example.com",
  "resolution": "string",
  "room_sid": "string",
  "sid": "string",
  "size": 42,
  "status": "enqueued",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}
Response examples (201) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "bitrate": 42,
  "date_completed": "2025-05-04T09:42:00Z",
  "date_created": "2025-05-04T09:42:00Z",
  "date_deleted": "2025-05-04T09:42:00Z",
  "duration": 42,
  "format": "mp4",
  "links": {},
  "media_external_location": "https://example.com",
  "resolution": "string",
  "room_sid": "string",
  "sid": "string",
  "size": 42,
  "status": "enqueued",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}

Returns a single Composition resource identified by a Composition SID

GET /v1/Compositions/{Sid}

Recording compositions

Returns a single Composition resource identified by a Composition SID.

Path parameters

  • Sid string Required

    The SID of the Composition resource to fetch.

Responses

  • 200

    OK

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • audio_sources array[string] | null

      The array of track names to include in the composition

    • audio_sources_excluded array[string] | null

      The array of track names to exclude from the composition

    • bitrate integer | null

      The average bit rate of the composition's media

    • date_completed string(date-time) | null

      Date when the media processing task finished

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_deleted string(date-time) | null

      The ISO 8601 date and time in GMT when the composition generated media was deleted

    • duration integer | null

      The duration of the composition's media file in seconds

    • format string | null

      The container format of the composition's media files as specified in the POST request that created the Composition resource

      Values are mp4 or webm.

    • links object(uri-map) | null

      The URL of the media file associated with the composition

    • media_external_location string(uri) | null

      The URL of the media file associated with the composition when stored externally

    • resolution string | null

      The dimensions of the video image in pixels expressed as columns (width) and rows (height)

    • room_sid string | null

      The SID of the Group Room that generated the audio and video tracks used in the composition

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RM[0-9a-fA-F]{32}$.

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CJ[0-9a-fA-F]{32}$.

    • size integer | null

      The size of the composed media file in bytes

    • status string | null

      The status of the composition

      Values are enqueued, processing, completed, deleted, or failed.

    • status_callback string(uri) | null

      The URL called to send status information on every composition event.

    • status_callback_method string(http-method) | null

      The HTTP method used to call status_callback

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • trim boolean | null

      Whether to remove intervals with no media

    • url string(uri) | null

      The absolute URL of the resource

    • video_layout

      An object that describes the video layout of the composition
GET /v1/Compositions/{Sid} 
curl \
 -X GET https://video.twilio.com/v1/Compositions/{Sid} \
 --user "username:password"
Response examples (200) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "bitrate": 42,
  "date_completed": "2023-05-04T09:42:00+00:00",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_deleted": "2023-05-04T09:42:00+00:00",
  "duration": 42,
  "format": "mp4",
  "links": {},
  "media_external_location": "https://example.com",
  "resolution": "string",
  "room_sid": "string",
  "sid": "string",
  "size": 42,
  "status": "enqueued",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}
Response examples (200) 
{
  "account_sid": "string",
  "audio_sources": [
    "string"
  ],
  "audio_sources_excluded": [
    "string"
  ],
  "bitrate": 42,
  "date_completed": "2025-05-04T09:42:00Z",
  "date_created": "2025-05-04T09:42:00Z",
  "date_deleted": "2025-05-04T09:42:00Z",
  "duration": 42,
  "format": "mp4",
  "links": {},
  "media_external_location": "https://example.com",
  "resolution": "string",
  "room_sid": "string",
  "sid": "string",
  "size": 42,
  "status": "enqueued",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "trim": true,
  "url": "https://example.com"
}

Delete a Recording Composition resource identified by a Composition SID

DELETE /v1/Compositions/{Sid}

Recording compositions

Delete a Recording Composition resource identified by a Composition SID.

Path parameters

  • Sid string Required

    The SID of the Composition resource to delete.

Responses

  • 204

    The resource was deleted successfully.

DELETE /v1/Compositions/{Sid} 
curl \
 -X DELETE https://video.twilio.com/v1/Compositions/{Sid} \
 --user "username:password"

Recording settings