Room management

Create a room (POST)

Call this API to create a live room.

Prototype

Method: POST
Access point: https://api.netless.link/v5/rooms

Request header

Pass in the following parameters in the request header:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	The SDK token, which can be obtained through one of the following methods: Get a test-purpose SDK token from Agora Console. See Get security credentials for your whiteboard project. Call the RESTful API. See Generate an SDK token. Use code samples. See Generate a token from your app server.
`region`	string	Required	Specifies a data center to process the request: `us-sv`: Silicon Valley, US, which provides services to North America and South America. `sg`: Singapore, which provides services to Singapore, East Asia, and Southeast Asia. `in-mum`: Mumbai, India, which provides services to India. `eu`: Frankfurt, Europe, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Request body

Parameter	Data type	Required/Optional	Description
`isRecord`	boolean	Optional	This function is not supported yet. This parameter is `false` by defaut for `us-sv`, `sg`, `in-mum`, `eu` region.
`limit`	integer	Optional	The maximum number of users with a `writer` or `admin` token who can be in the room at the same time. If you set this to `0`, there is no maximum. Agora recommends setting it to `0`.

Request example

POST /v5/rooms
Host: api.netless.link
token: NETLESSSDK_YWs9xxxxxxZGM2MjRi
region: us-sv
Content-Type: application/json
{
 "isRecord": false
}

HTTP response

For details about all possible response status codes, see the status code table.

If the status code is 201, the request is successful. The response returns the status code and corresponding parameters.

The following is a response example for a successful request:

"status": 201,
"body":
{
    "uuid": "4a5xxxxx6b",
    "teamUUID": "RMxxxxx5aw",
    "appUUID": "i54xxxxx1AQ",
	"isRecord": false,
    "isBan": false,
    "createdAt": "2021-01-18T06:56:29.432Z",
    "limit": 0
}

Description of parameters in the response:

Parameter	Data type	Description
`uuid`	string	The room UUID, which is the unique identifier of a room.
`teamUUID`	string	The unique identifier of the Agora Console account that creates the whiteboard project.
`appUUID`	string	The unique identifier of the whiteboard project.
`isRecord`	boolean	Whether recording is enabled for the room: `true`: Enabled. `false`: Not enabled.
`isBan`	boolean	Whether the room is disabled: `true`: Disabled. `false`: Not disabled.
`createdAt`	string	The UTC time when the room was created.
`limit`	integer	The maximum number of users with a `writer` or `admin` token who can be in the room at the same time. If you set it to `0`, there is no maximum.

If the status code is not 201, the request fails. The response body includes a message field that describes the reason for the failure.

Get room information (GET)

Call this API to get information about a room.

Prototype

Method: GET
Access point: https://api.netless.link/v5/rooms/{uuid}

Request header

Pass in the following parameters in the request header:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	A SDK token or room token with the `writer` or `admin` role. To get a SDK token, you can: Get a test-purpose SDK token from Agora Console. See Get security credentials for your whiteboard project. Call the RESTful API. See Generate an SDK token. Use code samples. See Generate a token from your app server.
`region`	string	Required	Specifies a data center to process the request: `us-sv`: Silicon Valley, US, which provides services to North America and South America. `sg`: Singapore, which provides services to Singapore, East Asia, and Southeast Asia. `in-mum`: Mumbai, India, which provides services to India. `eu`: Frankfurt, Europe, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Request path

The following parameters are required in the URL:

Parameter	Data type	Required/Optional	Description
`uuid`	string	Required	The room UUID, which is the unique identifier of a room. You can get it by calling the RESTful API to create a room or calling the RESTful API to get room information.

Request example

GET /v5/rooms/a7exxxxxxa69
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9xxxxxxM2MjRi

HTTP response

For details about all possible response status codes, see the status code table.

If the status code is 200, the request is successful. The response returns the status code and corresponding parameters.

The following is a response example for a successful request:

"status": 200,
"body":
{
    "uuid": "4axxxxx96b",
    "teamUUID": "RMmxxxxx5aw",
    "appUUID": "i5xxxxx1AQ",
	"isRecord": false,
    "isBan": false,
    "createdAt": "2021-01-18T06:56:29.432Z",
    "limit": 0
}

Description of parameters in the response:

Parameter	Data type	Description
`uuid`	string	The room UUID, which is the unique identifier of a room.
`teamUUID`	string	The unique identifier of the Agora Console account that creates the whiteboard project.
`appUUID`	string	The unique identifier of the whiteboard project.
`isRecord`	boolean	Whether recording is enabled for the room: `true`: Enabled. `false`: Not enabled.
`isBan`	boolean	Whether the room is disabled: `true`: Disabled. `false`: Not disabled.
`createdAt`	string	The UTC time when the room was created.
`limit`	integer	The maximum number of users with a `writer` or `admin` token who can be in the room at the same time. If you set it to 0, there is no maximum.

If the status code is not 200, the request fails. The response body includes a message field that describes the reason for the failure.

Get a room list (GET)

Call this API to get a list of rooms.

Prototype

Method: GET
Access point: https://api.netless.link/v5/rooms

Request header

Pass in the following parameters in the request header:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	A SDK token or room token with the `writer` or `admin` role. To get a SDK token, you can: Get a test-purpose SDK token from Agora Console. See Get security credentials for your whiteboard project. Call the RESTful API. See Generate an SDK token. Use code samples. See Generate a token from your app server.
`region`	string	Required	Specifies a data center to process the request: `us-sv`: Silicon Valley, US, which provides services to North America and South America. `sg`: Singapore, which provides services to Singapore, East Asia, and Southeast Asia. `in-mum`: Mumbai, India, which provides services to India. `eu`: Frankfurt, Europe, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Query parameters

You can choose to pass in the following query parameters:

Parameter	Data type	Required/Optional	Description
`beginUUID`	string	Optional	The UUID of the room you want to start querying from.
`limit`	integer	Optional	The maximum number of rooms on the list. The range is (0,1000]. If you do not set this parameter, the default maximum is 100 rooms.

Request example

GET /v5/rooms/?beginUUID=0e6exxxxxx4d95&limit=2
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9QlxxxxxxM2MjRi

HTTP response

For details about all possible response status codes, see the status code table.

If the status code is 200, the request is successful. The response returns the status code and corresponding parameters.

The following is a response example for a successful request:

"status": 200,
"body":
[
    {
        "uuid": "0e6exxxxxxd95",
        "teamUUID": "RMmxxxxxxaw",
        "appUUID": "vVxxxxzJF-A",
	    "isRecord": false,
        "isBan": false,
        "createdAt": "2020-12-20T14:02:54.846Z",
        "limit": 0
    },
    {
        "uuid": "1d4xxxxxxca69",
        "teamUUID": "RMmxxxxxx5aw",
        "appUUID": "vVsxxxxzJF-A",
	    "isRecord": false,
        "isBan": false,
        "createdAt": "2020-12-20T14:10:29.265Z",
        "limit": 0
    }
]

Description of parameters in the response:

Parameter	Data type	Description
`uuid`	string	The room UUID, which is the unique identifier of a room.
`teamUUID`	string	The unique identifier of the Agora Console account that creates the whiteboard project.
`appUUID`	string	The unique identifier of the whiteboard project.
`isRecord`	boolean	Whether recording is enabled for the room: `true`: Enabled. `false`: Not enabled.
`isBan`	boolean	Whether the room is disabled: `true`: Disabled. `false`: Not disabled.
`createdAt`	string	The UTC time when the room was created.
`limit`	integer	The maximum number of users with a `writer` or `admin` token who can be in the room at the same time.. If you set it to 0, there is no maximum.``

If the status code is not 200, the request fails. The response body includes a message field that describes the reason for the failure.``

Disable a room (PATCH)

Refer to the following information to disable or cancel disabling a room.

Note that when you disable a room, the users in the room will be removed and no users will be able to join the room.

If you want to cancel disabling the room, call the RESTful API again and set isBan to false.

Prototype

Method: PATCH
Access point: https://api.netless.link/v5/rooms/{uuid}

Request header

Pass in the following parameters in the request header:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	A SDK token or room token with the `admin` role. To get a SDK token, you can: Get a test-purpose SDK token from Agora Console. See Get security credentials for your whiteboard project. Call the RESTful API. See Generate an SDK token. Use code samples. See Generate a token from your app server.
`region`	string	Required	Specifies a data center to process the request: `us-sv`: Silicon Valley, US, which provides services to North America and South America. `sg`: Singapore, which provides services to Singapore, East Asia, and Southeast Asia. `in-mum`: Mumbai, India, which provides services to India. `eu`: Frankfurt, Europe, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Request path

The following parameters are required in the URL:

Parameter	Data type	Required/Optional	Description
`uuid`	string	Required	The room UUID, which is the unique identifier of a room. You can get it by calling the RESTful API to create a room or calling the RESTful API to get room information.

Request body

Parameter	Data type	Required/Optional	Description
`isBan`	boolean	Required	Whether the room is disabled: `true`: Disabled. `false`: (Default) Not disabled.

Request example

PATCH /v5/rooms/0e6exxxxxx4d95
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9xxxxxx5ZGM2MjRi
{
  "isBan": true
}

HTTP response

For details about all possible response status codes, see the status code table.

If the status code is 201, the request is successful. The response returns the status code and corresponding parameters.

The following is a response example for a successful request:

"status": 201,
"body":
{
    "uuid": "0e6xxxxxx95",
    "teamUUID": "RMxxxxxaw",
    "appUUID": "vVxxxxxJF-A",
	"isRecord": false,
    "isBan": true,
    "createdAt": "2020-12-20T14:02:54.846Z",
    "limit": 0
}

Description of parameters in the response:

Parameter	Data type	Description
Parameter	Data type	Description
`uuid`	string	The room UUID, which is the unique identifier of a room.
`teamUUID`	string	The unique identifier of the Agora Console account that creates the whiteboard project.
`appUUID`	string	The unique identifier of the whiteboard project.
`isRecord`	boolean	Whether recording is enabled for the room: `true`: Enabled. `false`: Not enabled.
`isBan`	boolean	Whether the room is disabled: `true`: Disabled. `false`: Not disabled.
`createdAt`	string	The UTC time when the room was created.
`limit`	integer	The maximum number of users with a `writer` or `admin` token who can be in the room at the same time. If you set it to `0`, there is no maximum.

If the status code is not 201, the request fails. The response body includes a message field that describes the reason for the failure.