100ms Logo

100ms

Docs

Search docs
/

Templates and Roles

Note: The Legacy API (V1) will remain fully functional. However, we recommend you use our new API to leverage the new functionalities and features and stay up to date with future releases; you can continue to check the docs for the Legacy API (V1)s here.

Create Template API

POST/policy/v1/templates
curl 'https://prod-policy.100ms.live/policy/v1/templates' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "name": "test-template", "default": true, "roles":{ "student": {}, "teacher": {}, "admin": {} } }'
RESPONSE
Status: 200 OK
{ "_id": "615e61b0ba65e77a89ba75c1", "name": "test-template", "customer": "60f7cc95f88117b9e47bf618", "default": true, "roles": { "admin": { "name": "admin", "publishParams": { "allowed": ["video", "screen", "audio"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 250, "codec": "vp8", "frameRate": 30, "width": 480, "height": 270 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 } }, "subscribeParams": { "subscribeToRoles": ["guest"], "maxSubsBitRate": 3200, "subscribeDegradation": {} }, "permissions": {} }, "student": { "name": "student", "publishParams": { "allowed": ["video", "screen", "audio"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 250, "codec": "vp8", "frameRate": 30, "width": 480, "height": 270 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 } }, "subscribeParams": { "subscribeToRoles": ["guest"], "maxSubsBitRate": 3200, "subscribeDegradation": {} }, "permissions": {} }, "teacher": { "name": "teacher", "publishParams": { "allowed": ["video", "screen", "audio"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 250, "codec": "vp8", "frameRate": 30, "width": 480, "height": 270 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 } }, "subscribeParams": { "subscribeToRoles": ["guest"], "maxSubsBitRate": 3200, "subscribeDegradation": {} }, "permissions": {} } } }

Body Parameters

NameTypeDescriptionRequired
name
stringA unique identifier you can assign to 100ms templates. Accepted characters are a-z, A-Z, 0-9, and . - : _. If not provided, this is generated automatically.

Notes:
(1) If create Template is called with an existing template name, then that template will be overwritten.
(2) Providing template name will be helpful if you want to modify/delete the template using name.
No
default
booleanWhether this is default template for a customer. Default template for a customer is used when no template is provided in create Room api.No
roles
objectMap of {roleName:roleObject}. Some sane defaults are set for values that are not provided in the roles object.No
settings
objectGlobal settings for this template.No

roleObject

NameTypeDescriptionRequired
publishParamsobjectPublish parameters for this role.No
subscribeParamsobjectSubscribe parameters for this role.No
permissionsobjectPermissions for this role.No
priorityintPriority of the role for subscription/publishing.
Range: 1-10
No

publishParams

NameTypeDescriptionRequired
allowedarrayAllowed tracks. Subarray of [audio, video, screen].No
audioobjectAudio publish parameters.No
videoobjectVideo publish parameters.No
screenobjectScreenshare publish parameters.No

audio

NameTypeDescriptionRequired
bitRateintAudio Max bitrate of audio track in kbps.
Range: 16-128
Default: 32
No
codecstringCodec for the audio track.
Options: [opus]
Default: opus
No

video

NameTypeDescriptionRequired
bitRateintMax bitrate of video track in kbps.
Range: 30-2000
Default: 256
No
codecstringCodec for the video track.
Options: [vp8]
Default: vp8
No
frameRateintMax number of video frames per second.
Range: 1-30
Default: 25
No
heightintHeight of the video track.
Range: 50-1080
Default: 180
No
widthintWidth of the video track.
Range: 50-1920
Default: 320
No

screen

NameTypeDescriptionRequired
bitRateintMax bitrate of screen track in kbps.
Range: >=500
Default: 1024
No
codecstringCodec for the screen track.
Options: [vp8]
Default: vp8
No
frameRateintMax number of screen frames per second
Range: 1-30
Default: 10
No
heightintHeight of the screen track.
Range: 270-1080
Default: 720
No
widthintWidth of the screen track.
Range: 480-1920
Default: 1280
No

subscribeParams

NameTypeDescriptionRequired
maxSubsBitRateintMaximum bitrate (in kbps) that can subscribed.No
subscribeToRolesarrayList of roles which can be subscribed to.No
subscribeDegradationobjectSubscribe degradation parameters (adding this enables screen simulcast).No

subscribeDegradation

NameTypeDescriptionRequired
packetLossThresholdintThreshold for packet loss.
Range: 1-100
Default: 50
No
degradeGracePeriodSecondsintDegrade grace period (in seconds).
Range: 1-10
Default: 1
No
recoverGracePeriodSecondsintRecover grace period (in seconds).
Range: 1-10
Default: 4
No

permissions

NameTypeDescriptionRequired
endRoombooleanPermission to end room for all.No
removeOthersbooleanPermission to remove others from the room.No
mutebooleanPermission to request others to mute them.No
unmutebooleanPermission to request others to unmute them.No
changeRolebooleanPermission to request others to change their role.No

settings

NameTypeDescriptionRequired
regionstringRegion in which the room will be hosted by default. Possible values could be in, us, eu or auto (automatic region selection).No
recordingobjectObject of type recording. This object contains information for enabling recording/setting storage location for recordings.No

recording

NameTypeDescriptionRequired
enabledbooleanEnable the SFU recording for its rooms. Disabled by default.No
uploadobjectObject of type upload. This object contains information on recordings storage location. If you want to store recording with 100ms, and not use your own s3, don't add this to the objectNo

upload

NameTypeDescriptionRequired
typestringUpload Destination type. Currently, only s3 is supported.Yes
locationstringName of the AWS s3 bucket in which you want to store all recordingsYes
prefixstringUpload prefix pathYes
optionsobjectAdditional configurations of type Options to be used for uploadingNo
credentialsobjectObject of type Credentials. This is used to share AWS credentials to access the s3 bucket specified.No

options

NameTypeDescriptionRequired
regionstringRegion of the AWS account hosting the s3 bucket. If not provided it is assumed to be ap-south-1No

Credentials

NameTypeDescriptionRequired
keystringaccess key ID for the AWS account hosting the s3 bucket for storing recordingsYes
secretstringsecret access key for the AWS account hosting the s3 bucket for storing recordingsYes

Create/Modify Role API

POST/policy/v1/templates/:id/roles/:name
curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "name": "listener3", "publishParams": { "allowed": [ "video", "screen", "audio" ], "audio": { "bitRate": 40, "codec": "opus" }, "video": { "bitRate": 400, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 } }, "subscribeParams": { "subscribeToRoles": [ "speaker", "moderator", "new-role-9880" ], "maxSubsBitRate": 3200, "subscribeDegradation": {} }, "permissions": {}, "priority": 1 }'
RESPONSE
Status: 200 OK
{ "name": "listener3", "publishParams": { "allowed": ["video", "screen", "audio"], "audio": { "bitRate": 40, "codec": "opus" }, "video": { "bitRate": 400, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 } }, "subscribeParams": { "subscribeToRoles": ["speaker", "moderator", "new-role-9880"], "maxSubsBitRate": 3200, "subscribeDegradation": {} }, "permissions": {}, "priority": 1 }

Body Parameters

NameTypeDescriptionRequired
roleObject
objectRole object correspoding to the given role.Yes
name
stringProviding a name renames the role to the provided name. If role with same name already exists, it gives an overwrite error.No

Update Settings API

POST/policy/v1/templates/:id/settings
curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/settings' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "region": "us" }'
RESPONSE
Status: 200 OK
{ "region": "us" }

Body Parameters

NameTypeDescriptionRequired
region
stringRegion in which the room will be hosted by default - in, eu, us or auto.No

Get Templates API

GET/policy/v1/templates?id=ID
curl 'https://prod-policy.100ms.live/policy/v1/templates?id={{templateID}}' -H 'Authorization: Bearer {{management_token}}'
RESPONSE
Status: 200 OK
{ "limit": 10, "data": [ { "_id": "615dbca1ba65e77a89a8e2b8", "name": "test-template10", "customer": "60f7cc95f88117b9e47bf618", "roles": { "student": { "name": "student", "publishParams": { "allowed": ["screen", "audio"], "audio": { "bitRate": 42, "codec": "opus" }, "video": { "bitRate": 250, "codec": "vp8", "frameRate": 30, "width": 480, "height": 270 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1086 } }, "subscribeParams": { "subscribeToRoles": ["teacher", "student"], "maxSubsBitRate": 2000, "subscribeDegradation": {} }, "permissions": {}, "priority": 1 } }, "settings": { "region": "in" } } ], "last": "615dbca1ba65e77a89a8e2b8" }

URL Parameters

NameTypeDescriptionRequired
name
stringName of the template.No
id
stringID of the template.No
start
stringReturned dataset is sorted by decreasing order of IDs. Provide the ID of the last result set to start in reverse order from there.No
limit
intNumber of templates to return (max 20).No
default
booleanWhether template is default or not.No

Get Role API

GET/policy/v1/templates/:id/roles/:name
curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}' -H 'Authorization: Bearer {{management_token}}'
RESPONSE
Status: 200 OK
{ "name": "student", "publishParams": { "allowed": ["screen", "audio"], "audio": { "bitRate": 42, "codec": "opus" }, "video": { "bitRate": 250, "codec": "vp8", "frameRate": 30, "width": 480, "height": 270 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1086 } }, "subscribeParams": { "subscribeToRoles": ["teacher", "student"], "maxSubsBitRate": 2000, "subscribeDegradation": {} }, "permissions": {}, "priority": 1 }

Get Settings API

GET/policy/v1/templates/:id/settings
curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/settings' -H 'Authorization: Bearer {{management_token}}'
RESPONSE
Status: 200 OK
{ "region": "in" }

Modify Template API

POST/policy/v1/templates?id=ID
curl 'https://prod-policy.100ms.live/policy/v1/templates?id={{templateID}}' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "roles":{ "student":{ "name":"student", "publishParams":{ "allowed":[ "screen", "audio" ], "audio":{ "bitRate":42, "codec":"opus" }, "video":{ "bitRate":250, "codec":"vp8", "frameRate":30, "width":480, "height":270 }, "screen":{ "codec":"vp8", "frameRate":10, "width":1920, "height":1086 } }, "subscribeParams":{ "subscribeToRoles":[ "teacher", "student" ], "maxSubsBitRate":2000 }, "priority":1 } }, "settings":{ "region":"eu" } }'
RESPONSE
Status: 200 OK
{ "_id": "615dbca1ba65e77a89a8e2b8", "name": "test-template10", "customer": "60f7cc95f88117b9e47bf618", "roles": { "student": { "name": "student", "publishParams": { "allowed": ["screen", "audio"], "audio": { "bitRate": 42, "codec": "opus" }, "video": { "bitRate": 250, "codec": "vp8", "frameRate": 30, "width": 480, "height": 270 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1086 } }, "subscribeParams": { "subscribeToRoles": ["teacher", "student"], "maxSubsBitRate": 2000, "subscribeDegradation": {} }, "permissions": {}, "priority": 1 } }, "settings": { "region": "eu" } }

Body Parameters

NameTypeDescriptionRequired
name
stringIf you don't provide the name, earlier provided name is used. Trying to modify a template's name to match another existing template's name produces overwrite error.No
default
booleanWhether this is default template for customer. The default template for a customer is used when no template is provided in create room API.No
roles
objectModified map of {roleName:roleObject}. Since this is a POST request, you need to provide the whole roles object to modify/persist/override it.Yes
settings
objectModified settings. Since this is a POST request, you need to provide the whole settings object to modify/persist/override it.Yes

Delete Role API

DELETE/policy/v1/templates/:id/roles/:name
curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}' -H 'Authorization: Bearer {{management_token}}' -X DELETE -H 'Content-Type: application/json'
RESPONSE
Status: 204 No Content


Run in postman