openapi: 3.1.0 info: title: Twilio Video API description: >- Build real-time video communication applications with Twilio's Video API. Create and manage video rooms, control participants, manage recordings and compositions, and configure recording rules. version: '2.0' 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 termsOfService: https://www.twilio.com/legal/tos externalDocs: description: Twilio Video API Documentation url: https://www.twilio.com/docs/video servers: - url: https://video.twilio.com/v1 description: Twilio Video API v1 tags: - name: Composition Hooks description: Configure automatic composition rules - name: Compositions description: Compose multiple recordings into a single file - name: Participants description: Manage room participants - name: Recording Rules description: Manage recording rules for rooms - name: Recordings description: Manage video and audio recordings - name: Rooms description: Create and manage video rooms security: - accountSid_authToken: [] paths: /Rooms: get: operationId: listRooms summary: Twilio List Rooms description: >- Retrieve a list of video rooms in your account. tags: - Rooms parameters: - name: Status in: query description: Filter by room status schema: type: string enum: - in-progress - completed - name: UniqueName in: query description: Filter by unique room name schema: type: string - name: DateCreatedAfter in: query schema: type: string format: date-time - name: DateCreatedBefore in: query schema: type: string format: date-time - name: PageSize in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: List of rooms content: application/json: schema: $ref: '#/components/schemas/RoomList' '401': description: Unauthorized post: operationId: createRoom summary: Twilio Create a Room description: >- Create a new video room. Rooms can be configured as group rooms (up to 50 participants), small group rooms (up to 4), or peer-to-peer rooms (up to 10). tags: - Rooms requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateRoomRequest' responses: '201': description: Room created content: application/json: schema: $ref: '#/components/schemas/Room' '400': description: Invalid request '401': description: Unauthorized /Rooms/{RoomSid}: get: operationId: fetchRoom summary: Twilio Fetch a Room description: >- Retrieve details of a specific video room. tags: - Rooms parameters: - $ref: '#/components/parameters/RoomSid' responses: '200': description: Room details content: application/json: schema: $ref: '#/components/schemas/Room' '404': description: Room not found post: operationId: updateRoom summary: Twilio Update a Room description: >- End an in-progress room by setting its status to completed. tags: - Rooms parameters: - $ref: '#/components/parameters/RoomSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - Status properties: Status: type: string enum: - completed description: Set to completed to end the room responses: '200': description: Room updated content: application/json: schema: $ref: '#/components/schemas/Room' '404': description: Room not found /Rooms/{RoomSid}/Participants: get: operationId: listParticipants summary: Twilio List Room Participants description: >- Retrieve a list of participants who have connected to a room. tags: - Participants parameters: - $ref: '#/components/parameters/RoomSid' - name: Status in: query schema: type: string enum: - connected - disconnected - name: Identity in: query schema: type: string - name: PageSize in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: List of participants content: application/json: schema: $ref: '#/components/schemas/VideoParticipantList' '404': description: Room not found /Rooms/{RoomSid}/Participants/{ParticipantSid}: get: operationId: fetchParticipant summary: Twilio Fetch a Participant tags: - Participants parameters: - $ref: '#/components/parameters/RoomSid' - $ref: '#/components/parameters/ParticipantSid' responses: '200': description: Participant details content: application/json: schema: $ref: '#/components/schemas/VideoParticipant' '404': description: Participant not found post: operationId: updateParticipant summary: Twilio Disconnect a Participant description: >- Remove a participant from a room by setting their status to disconnected. tags: - Participants parameters: - $ref: '#/components/parameters/RoomSid' - $ref: '#/components/parameters/ParticipantSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - Status properties: Status: type: string enum: - disconnected responses: '200': description: Participant disconnected content: application/json: schema: $ref: '#/components/schemas/VideoParticipant' /Rooms/{RoomSid}/Participants/{ParticipantSid}/PublishedTracks: get: operationId: listPublishedTracks summary: Twilio List Published Tracks description: >- List the tracks a participant has published to a room. tags: - Participants parameters: - $ref: '#/components/parameters/RoomSid' - $ref: '#/components/parameters/ParticipantSid' responses: '200': description: List of published tracks content: application/json: schema: $ref: '#/components/schemas/PublishedTrackList' /Rooms/{RoomSid}/Participants/{ParticipantSid}/SubscribeRules: get: operationId: fetchSubscribeRules summary: Twilio Fetch Subscribe Rules tags: - Participants parameters: - $ref: '#/components/parameters/RoomSid' - $ref: '#/components/parameters/ParticipantSid' responses: '200': description: Subscribe rules content: application/json: schema: $ref: '#/components/schemas/SubscribeRules' post: operationId: updateSubscribeRules summary: Twilio Update Subscribe Rules description: >- Update the subscribe rules for a participant to control which tracks they receive. tags: - Participants parameters: - $ref: '#/components/parameters/RoomSid' - $ref: '#/components/parameters/ParticipantSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: Rules: type: string description: JSON array of subscribe rules responses: '200': description: Subscribe rules updated /Rooms/{RoomSid}/Recordings: get: operationId: listRoomRecordings summary: Twilio List Room Recordings tags: - Recordings parameters: - $ref: '#/components/parameters/RoomSid' - name: Status in: query schema: type: string enum: - processing - completed - deleted - failed - name: PageSize in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: List of recordings content: application/json: schema: $ref: '#/components/schemas/VideoRecordingList' /Rooms/{RoomSid}/RecordingRules: get: operationId: fetchRecordingRules summary: Twilio Fetch Recording Rules tags: - Recording Rules parameters: - $ref: '#/components/parameters/RoomSid' responses: '200': description: Recording rules content: application/json: schema: $ref: '#/components/schemas/RecordingRules' post: operationId: updateRecordingRules summary: Twilio Update Recording Rules description: >- Update the recording rules for a room to control which tracks are recorded. tags: - Recording Rules parameters: - $ref: '#/components/parameters/RoomSid' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: Rules: type: string description: JSON array of recording rules responses: '200': description: Recording rules updated /Recordings/{RecordingSid}: get: operationId: fetchRecording summary: Twilio Fetch a Recording tags: - Recordings parameters: - name: RecordingSid in: path required: true schema: type: string pattern: ^RT[0-9a-fA-F]{32}$ responses: '200': description: Recording details content: application/json: schema: $ref: '#/components/schemas/VideoRecording' '404': description: Recording not found delete: operationId: deleteRecording summary: Twilio Delete a Recording tags: - Recordings parameters: - name: RecordingSid in: path required: true schema: type: string pattern: ^RT[0-9a-fA-F]{32}$ responses: '204': description: Recording deleted '404': description: Recording not found /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 /CompositionHooks: get: operationId: listCompositionHooks summary: Twilio List Composition Hooks tags: - Composition Hooks parameters: - name: Enabled in: query schema: type: boolean - name: PageSize in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: List of composition hooks content: application/json: schema: $ref: '#/components/schemas/CompositionHookList' post: operationId: createCompositionHook summary: Twilio Create a Composition Hook description: >- Create a composition hook that automatically generates compositions when rooms complete. tags: - Composition Hooks requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateCompositionHookRequest' responses: '201': description: Composition hook created content: application/json: schema: $ref: '#/components/schemas/CompositionHook' /CompositionHooks/{CompositionHookSid}: get: operationId: fetchCompositionHook summary: Twilio Fetch a Composition Hook tags: - Composition Hooks parameters: - name: CompositionHookSid in: path required: true schema: type: string pattern: ^HK[0-9a-fA-F]{32}$ responses: '200': description: Composition hook details content: application/json: schema: $ref: '#/components/schemas/CompositionHook' post: operationId: updateCompositionHook summary: Twilio Update a Composition Hook tags: - Composition Hooks parameters: - name: CompositionHookSid in: path required: true schema: type: string pattern: ^HK[0-9a-fA-F]{32}$ requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateCompositionHookRequest' responses: '200': description: Composition hook updated delete: operationId: deleteCompositionHook summary: Twilio Delete a Composition Hook tags: - Composition Hooks parameters: - name: CompositionHookSid in: path required: true schema: type: string pattern: ^HK[0-9a-fA-F]{32}$ responses: '204': description: Composition hook deleted /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 /RecordingSettings/Default: get: operationId: fetchRecordingSettings summary: Twilio Fetch Recording Settings tags: - Recordings responses: '200': description: Recording settings content: application/json: schema: $ref: '#/components/schemas/RecordingSettings' post: operationId: createRecordingSettings summary: Twilio Create or Update Recording Settings description: >- Configure the AWS credentials and S3 bucket for storing recordings. tags: - Recordings 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: Recording settings created components: securitySchemes: accountSid_authToken: type: http scheme: basic description: >- Use your Twilio Account SID as the username and Auth Token as the password for HTTP Basic authentication. parameters: RoomSid: name: RoomSid in: path required: true description: The SID or unique name of the room schema: type: string ParticipantSid: name: ParticipantSid in: path required: true description: The SID of the participant schema: type: string pattern: ^PA[0-9a-fA-F]{32}$ schemas: Room: type: object properties: sid: type: string pattern: ^RM[0-9a-fA-F]{32}$ description: Unique identifier for the room account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ unique_name: type: string description: Unique name of the room status: type: string enum: - in-progress - completed - failed description: Current status of the room type: type: string enum: - go - peer-to-peer - group - group-small description: Type of room max_participants: type: integer description: Maximum number of participants allowed max_participant_duration: type: integer description: Maximum duration per participant in seconds max_concurrent_published_tracks: type: integer description: Maximum number of published tracks duration: type: integer description: Duration of the room in seconds record_participants_on_connect: type: boolean description: Whether to record participants upon connection video_codecs: type: array items: type: string enum: [VP8, H264] media_region: type: string description: Region where media is processed audio_only: type: boolean empty_room_timeout: type: integer description: Minutes before an empty room times out unused_room_timeout: type: integer description: Minutes before an unused room times out end_time: type: string format: date-time date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri links: type: object properties: participants: type: string format: uri recordings: type: string format: uri recording_rules: type: string format: uri RoomList: type: object properties: rooms: type: array items: $ref: '#/components/schemas/Room' meta: $ref: '#/components/schemas/PaginationMeta' CreateRoomRequest: type: object properties: UniqueName: type: string description: Unique name for the room Type: type: string enum: - go - peer-to-peer - group - group-small default: group description: Type of room MaxParticipants: type: integer description: Maximum number of concurrent participants default: 50 MaxParticipantDuration: type: integer description: Maximum participant duration in seconds default: 14400 RecordParticipantsOnConnect: type: boolean description: Whether to automatically record participants default: false VideoCodecs: type: array items: type: string enum: [VP8, H264] MediaRegion: type: string description: Region where media is processed StatusCallback: type: string format: uri description: URL for room event webhooks StatusCallbackMethod: type: string enum: [GET, POST] EmptyRoomTimeout: type: integer description: Minutes to keep an empty room alive UnusedRoomTimeout: type: integer description: Minutes to keep an unused room alive AudioOnly: type: boolean description: Create an audio-only room VideoParticipant: type: object properties: sid: type: string pattern: ^PA[0-9a-fA-F]{32}$ description: Unique identifier for the participant room_sid: type: string pattern: ^RM[0-9a-fA-F]{32}$ account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ identity: type: string description: User identity of the participant status: type: string enum: - connected - disconnected duration: type: integer description: Duration the participant was connected start_time: type: string format: date-time end_time: type: string format: date-time date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri links: type: object properties: published_tracks: type: string format: uri subscribe_rules: type: string format: uri subscribed_tracks: type: string format: uri VideoParticipantList: type: object properties: participants: type: array items: $ref: '#/components/schemas/VideoParticipant' meta: $ref: '#/components/schemas/PaginationMeta' PublishedTrack: type: object properties: sid: type: string pattern: ^MT[0-9a-fA-F]{32}$ participant_sid: type: string pattern: ^PA[0-9a-fA-F]{32}$ room_sid: type: string pattern: ^RM[0-9a-fA-F]{32}$ name: type: string description: Track name kind: type: string enum: [audio, video, data] enabled: type: boolean date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri PublishedTrackList: type: object properties: published_tracks: type: array items: $ref: '#/components/schemas/PublishedTrack' meta: $ref: '#/components/schemas/PaginationMeta' SubscribeRules: type: object properties: participant_sid: type: string room_sid: type: string rules: type: array items: type: object properties: type: type: string enum: [include, exclude] all: type: boolean kind: type: string enum: [audio, video, data] publisher: type: string track: type: string date_created: type: string format: date-time date_updated: type: string format: date-time RecordingRules: type: object properties: room_sid: type: string rules: type: array items: type: object properties: type: type: string enum: [include, exclude] all: type: boolean kind: type: string enum: [audio, video] publisher: type: string track: type: string date_created: type: string format: date-time date_updated: type: string format: date-time VideoRecording: type: object properties: sid: type: string pattern: ^RT[0-9a-fA-F]{32}$ description: Unique identifier for the recording account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ room_sid: type: string pattern: ^RM[0-9a-fA-F]{32}$ source_sid: type: string description: SID of the track being recorded status: type: string enum: - processing - completed - deleted - failed type: type: string enum: [audio, video] duration: type: integer description: Duration in seconds size: type: integer description: Size of the recording in bytes container_format: type: string enum: [mka, mkv] codec: type: string enum: [VP8, H264, OPUS, PCMU] grouping_sids: type: object description: Grouping identifiers track_name: type: string offset: type: integer description: Offset in milliseconds from room start media_external_location: type: string format: uri date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri links: type: object properties: media: type: string format: uri VideoRecordingList: type: object properties: recordings: type: array items: $ref: '#/components/schemas/VideoRecording' meta: $ref: '#/components/schemas/PaginationMeta' 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 CompositionList: type: object properties: compositions: type: array items: $ref: '#/components/schemas/Composition' meta: $ref: '#/components/schemas/PaginationMeta' 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] CompositionHook: type: object properties: sid: type: string pattern: ^HK[0-9a-fA-F]{32}$ account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ friendly_name: type: string enabled: type: boolean video_layout: type: object audio_sources: type: array items: type: string audio_sources_excluded: type: array items: type: string resolution: type: string format: type: string enum: [mp4, webm] trim: type: boolean status_callback: type: string format: uri status_callback_method: type: string date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri CompositionHookList: type: object properties: composition_hooks: type: array items: $ref: '#/components/schemas/CompositionHook' meta: $ref: '#/components/schemas/PaginationMeta' CreateCompositionHookRequest: type: object required: - FriendlyName properties: FriendlyName: type: string Enabled: type: boolean default: true VideoLayout: type: string AudioSources: type: array items: type: string AudioSourcesExcluded: type: array items: type: string Resolution: type: string Format: type: string enum: [mp4, webm] Trim: type: boolean StatusCallback: type: string format: uri StatusCallbackMethod: type: string enum: [GET, POST] 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 RecordingSettings: 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 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