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


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

Name	Type	Description	Required
name	`string`	A unique name you can assign to 100ms templates. Accepted characters are a-z, A-Z, 0-9, space, hyphen `-`, dot `.`, underscore `_` and colon `:`. If not provided, this is generated automatically. Notes: If `create template` is called with an existing template name, then that template will be overwritten.	No
default	`boolean`	Whether 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	`object`	Map of `{roleName:roleObject}`. Some sane defaults are set for values that are not provided in the roles object.	No
settings	`object`	Global settings for this template.	No

roleObject

Name	Type	Description	Required
publishParams	`object`	Publish parameters for this role.	No
subscribeParams	`object`	Subscribe parameters for this role.	No
permissions	`object`	Permissions for this role.	No
priority	`int`	Priority of the role for subscription/publishing. Range: `1`-`10`	No

publishParams

Name	Type	Description	Required
allowed	`array`	Allowed tracks. Subarray of [`audio`, `video`, `screen`].	No
audio	`object`	Audio publish parameters.	No
video	`object`	Video publish parameters.	No
screen	`object`	Screenshare publish parameters.	No

audio

Name	Type	Description	Required
bitRate	`int`	Audio Max bitrate of audio track in kbps. Range: `16`-`128` Default: `32`	No
codec	`string`	Codec for the audio track. Options: [`opus`] Default: `opus`	No

video

Name	Type	Description	Required
bitRate	`int`	Max bitrate of video track in kbps. Range: `30`-`2000` Default: `256`	No
codec	`string`	Codec for the video track. Options: [`vp8`] Default: `vp8`	No
frameRate	`int`	Max number of video frames per second. Range: `1`-`30` Default: `25`	No
height	`int`	Height of the video track. Range: `50`-`1080` Default: `180`	No
width	`int`	Width of the video track. Range: `50`-`1920` Default: `320`	No

screen

Name	Type	Description	Required
bitRate	`int`	Max bitrate of screen track in kbps. Range: `>=500` Default: `1024`	No
codec	`string`	Codec for the screen track. Options: [`vp8`] Default: `vp8`	No
frameRate	`int`	Max number of screen frames per second Range: `1`-`30` Default: `10`	No
height	`int`	Height of the screen track. Range: `270`-`1080` Default: `720`	No
width	`int`	Width of the screen track. Range: `480`-`1920` Default: `1280`	No

subscribeParams

Name	Type	Description	Required
maxSubsBitRate	`int`	Maximum bitrate (in kbps) that can subscribed.	No
subscribeToRoles	`array`	List of roles which can be subscribed to.	No
subscribeDegradation	`object`	Subscribe degradation parameters (adding this enables screen simulcast).	No

subscribeDegradation

Name	Type	Description	Required
packetLossThreshold	`int`	Threshold for packet loss. Range: `1`-`100` Default: `50`	No
degradeGracePeriodSeconds	`int`	Degrade grace period (in seconds). Range: `1`-`10` Default: `1`	No
recoverGracePeriodSeconds	`int`	Recover grace period (in seconds). Range: `1`-`10` Default: `4`	No

permissions

Name	Type	Description	Required
endRoom	`boolean`	Permission to end room for all.	No
removeOthers	`boolean`	Permission to remove others from the room.	No
mute	`boolean`	Permission to request others to mute them.	No
unmute	`boolean`	Permission to request others to unmute them.	No
changeRole	`boolean`	Permission to request others to change their role.	No

settings

Name	Type	Description	Required
region	`string`	Region in which the room will be hosted by default. Possible values could be `in`, `us`, `eu` or `auto` (automatic region selection).	No
recording	`object`	Object of type `recording`. This object contains information for enabling recording/setting storage location for recordings.	No

recording

Name	Type	Description	Required
enabled	`boolean`	Enable the SFU recording for its rooms. Disabled by default.	No
upload	`object`	Object 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 object	No

upload

Name	Type	Description	Required
type	`string`	Upload Destination type. Currently, only s3 is supported.	Yes
location	`string`	Name of the AWS s3 bucket in which you want to store all recordings	Yes
prefix	`string`	Upload prefix path	Yes
options	`object`	Additional configurations of type Options to be used for uploading	No
credentials	`object`	Object of type `Credentials`. This is used to share AWS credentials to access the s3 bucket specified.	No

options

Name	Type	Description	Required
region	`string`	Region of the AWS account hosting the s3 bucket. If not provided it is assumed to be `ap-south-1`	No

Credentials

Name	Type	Description	Required
key	`string`	`access key ID` for the AWS account hosting the s3 bucket for storing recordings	Yes
secret	`string`	`secret access key` for the AWS account hosting the s3 bucket for storing recordings	Yes

Create/Modify Role API


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

Name	Type	Description	Required
roleObject	`object`	Role object correspoding to the given role.	Yes
name	`string`	Providing 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


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

Name	Type	Description	Required
region	`string`	Region in which the room will be hosted by default - `in`, `eu`, `us` or `auto`.	No

Get Templates API


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

Name	Type	Description	Required
name	`string`	Name of the template.	No
id	`string`	ID of the template.	No
start	`string`	Returned 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	`int`	Number of templates to return (max `20`).	No
default	`boolean`	Whether template is default or not.	No

Get Role API


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


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


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

Name	Type	Description	Required
name	`string`	If 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	`boolean`	Whether 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	`object`	Modified 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	`object`	Modified settings. Since this is a POST request, you need to provide the whole settings object to modify/persist/override it.	Yes

Delete Role API


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

Session SFU Recording

Have a suggestion? Recommend changes ->