Create via API

Creates a new room. This provides a more scalable way of creating a room.

POSThttps://api.100ms.live/v2/rooms
curl --location --request POST 'https://api.100ms.live/v2/rooms' \ --header 'Authorization: Bearer <management_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "new-room-1662723668", "description": "This is a sample description for the room", "template_id": "<template_id of the template you wish to associate with the room>" }'
RESPONSE
Status: 200 OK
{ "id": "631b2654f771854d9bf633df", "name": "new-room-1662723668", "enabled": true, "description": "This is a sample description for the room", "customer_id": "627cdddff2e4e30487862ad1", "app_id":"62510797903d857ab8ec3ba5", "recording_info": { "enabled": false }, "template_id": "63188115d11d6db790c73c60", "template": "sample-template-name", "region": "us", "created_at": "2022-09-09T11:41:08.082Z", "updated_at": "2022-09-09T11:41:08.074Z" }

Main Arguments

NameTypeDescriptionRequired
name
stringAn alias you can assign to 100ms rooms. This is case-insensitive.

Accepted characters are a-z, A-Z, 0-9, and . - : _. If not provided, this is generated automatically.

Note: If Create room request is triggered with an existing room name, then the corresponding room ID is returned.
No
description
stringA string to describe your room's usage. For example "9PM English Class Batch 2"No
template_id
stringTemplate ID of template you wish to associate with the room. You can get template ID either from the templates section on the dashboard or use the Template API.

Note: default template will be assigned if template is not specified in the create room request.
No
recording_info
objectObject of type recording_info. This object contains information for enabling recording/setting storage location for recordings.

Check the recording_info arguments below for more information.
No
region
stringRegion in which you want to create a room.

eu - European Union

in - India

us - United States


auto Fallback to region of the template (default value)
No
large_room
booleanEnable this flag if the requirement is to support more than 2500 peers in the room. You are also required to update to latest SDKs to support this functionality. By default, this value is set to false. Learn more about it in the large room creation guide.No
size
intThis value is used to define the maximum number of peers expected to be joining the given room. Following are the acceptable ranges:

With large_room: false, Minimum size = 0; Maximum size = 2500

With large_room: true, Minimum size = 0; Maximum size = 20000
No
max_duration_seconds
intThis value is used to define the maximum duration in seconds for a room session. Following are the acceptable ranges:
Minimum max_duration_seconds = 120
Maximum max_duration_seconds = 43200

No
webhook
objectObject of type webhook. This object encapsulates information pertaining to webhooks including URL and headers.
It is designed for use in scenarios when there is a need to receive room events at a designated endpoint.

For further details, please refer to the webhook arguments section.
No

Warning: If you create a room with the name of an existing room, the same room will be updated with the new configuration passed in the request payload.
For example, if the existing room was assigned to 'template-ABC' earlier and in the request payload you've used 'template-DEF', then 'template-DEF' will be assigned to the existing room.

webhook arguments

NameTypeDescriptionRequired
urlstringSpecifies the URL for the webhook.Yes
headersobjectDefines custom HTTP request headers (in the form of key-value pairs) that should be applied to HTTP requests targeting the specified URL.No

Note: If you set webhooks on a room, then the workspace level webhooks (if set) won't be used.

recording info arguments

Note: This object enables recording and configuring storage during room creation. But we recommend configuring it at a template level through the Dashboard, where the config validator can help with validating inputs proactively.

NameTypeDescriptionRequired
enabledbooleanEnable SFU recording. Disabled by default.

Note: This argument is only applicable to enable/disable SFU recording. Refer to RTMP Streaming & Browser Recording guide for other options.
No
upload_infoobjectObject of type upload_info. This object contains information on recordings storage location.

If you want to store recording with 100ms, and not use your own storage (s3/gs/oss), don't add this to the object.

Check the upload_info object below for more information.
No
pollsarrayArray of poll ids that this room will have.No

recording_info in the room acts as an atomic property. It depends on the recording settings defined in a template as below:

  • If the recording_info key is not provided in the API, the room will fill it with recording settings from the template. And the response body will include recording_source_template: true. This implies that whenever recording info is modified in the template, the recording settings for the room will also be updated.
  • If the recording_info key is provided in the API, the recording settings of the room won't be affected by the template at all.

To know more about recording please visit Recording.

upload_info arguments

NameTypeDescriptionRequired
typestringUpload destination type. Currently, s3 (AWS), gs (Google Cloud Storage), oss (Alibaba Cloud) are supported.Yes
locationstringName of the storage bucket in which you want to store all recordingsYes
prefixstringUpload prefix pathNo
optionsobjectAdditional configurations of type Options to be used for uploading.

Check the options arguments below for more information.
No
credentialsobjectObject of type credentials. This is used to share the credentials to access the storage bucket specified.No

Options arguments

NameTypeDescriptionRequired
regionstringRegion of the account hosting the storage bucket for storing recordings.No

Credentials arguments

NameTypeDescriptionRequired
keystringAccess Key for the account hosting your storage bucket for storing recordingsYes
secretstringSecret for the account hosting the storage bucket for storing recordingsYes

The access keys should have read(GetObject) and write(PutObject) permissions for the storage bucket. For more details check - https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

Errors

More info on API errors here - https://www.100ms.live/docs/server-side/v2/how-to-guides/make-api-calls#errors

DescriptionCode
Authentication error401
Token validation error401
Bucket location is missing400
Invalid upload configuration400
Invalid body param: template. Use template_id400
Error: region not supported400
Error: template not found400
Invalid body param: max_duration_seconds less than 120 seconds400
Invalid body param: max_duration_seconds greater than 43200 seconds400

Have a suggestion? Recommend changes ->

Run in postman

Was this helpful?

1234