# Scene management (/en/api-reference/api-ref/whiteboard/scene-management)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## Get scene path list (GET) [#get-scene-path-list-get]
Call this API to get a list of scene paths in a room.
### Prototype [#prototype]
* Method: `GET`
* Access point: `https://api.netless.link/v5/rooms/{uuid}/scenes`
### Request header [#request-header]
Pass in the following parameters in the request header:
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | Required | An SDK token or room token with the `writer` or `admin` role. To get an SDK token, you can:- Get a test-purpose SDK token from Agora Console. See [Get security credentials for your whiteboard project](/en/realtime-media/whiteboard/build/set-up-and-build-your-first-app/enable-whiteboard.md#get-security-credentials-for-your-whiteboard-project).
- Call the RESTful API. See [Generate an SDK token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
To get a room token, you can:- Call the RESTful API. See [Generate a Room Token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md#generate-a-room-token-post).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
|
| `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 [#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](./room-management#create-a-room-post) or calling the [RESTful API to get room information](./room-management#get-room-information-get). |
### Query parameters [#query-parameters]
You can choose to pass in the following query parameters:
| Parameter | Data type | Required/Optional | Description |
| :--------- | :-------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sceneDir` | string | Optional | The path to the scene directory, which starts with `/`. If you pass in this parameter, a list of the scene paths under the specified directory is generated. If you do not pass it in, a list of the scene paths under the current directory is generated. |
### Request example [#request-example]
```bash
GET /v5/rooms/faexxxxx47c/scenes?sceneDir=/test
Host: api.netless.link
region: us-sv
token: NETLESSSDK_YWs9T3YtxxxxxYjc0
Content-Type: application/json
```
### HTTP response [#http-response]
For details about all possible response status codes, see the [status code table](./index#status-codes).
If the status code is `200`, the request is successful. The response returns the status code and corresponding parameters.
**Response example**
```json
"status": 200,
"body":
[
"/test/cover",
"/test/page1"
]
```
The response body is a JSON Array of scene path strings.
If the status code is not `200`, the request fails. The response body includes a `message` field that describes the reason for the failure.
## Add a scene (POST) [#add-a-scene-post]
Call this API to add a scene.
### Prototype [#prototype-1]
* Method: `POST`
* Access point: `https://api.netless.link/v5/rooms/{uuid}/scenes`
### Request header [#request-header-1]
Pass in the following parameters in the request header:
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | Required | An SDK token or room token with the `writer` or `admin` role. To get an SDK Token, you can:- Get a test-purpose SDK token from Agora Console. See [Get security credentials for your whiteboard project](/en/realtime-media/whiteboard/build/set-up-and-build-your-first-app/enable-whiteboard.md#get-security-credentials-for-your-whiteboard-project).
- Call the RESTful API. See [Generate an SDK token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
To get a room token, you can:- Call the RESTful API. See [Generate a room token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md#generate-a-room-token-post).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
|
| `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 [#request-path-1]
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](./room-management#create-a-room-post) or calling the [RESTful API to get room information](./room-management#get-room-information-get). |
### Request Body [#request-body]
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scenes` | array | Required | An array of scenes, each containing the following parameters:- `name`: String. Sets the scene name. It cannot be the same as another scene in the same group and cannot contain `/`.
- `ppt`: (Optional) Object. Sets the property of the background image of the scene.
- `src`: String. Sets the URL of the image. Ensure that your browser can access and display the image properly; otherwise, the image may not be displayed in the scene.
- `width`: Number. Sets the width of the image in pixels.
- `height`: Number. Sets the height of the image in pixels.
|
| `path` | string | Required | The path of a scene directory.If the path already exists, the new scene is added under the existing scene directory; if not, a new scene directory is created, and the new scene is added under the created directory. |
### Request example [#request-example-1]
```bash
POST /v5/rooms/a7e0xxxxxa69/scenes
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9QlxxxxxA0NzA5ZGM2MjRi
{
"scenes": [
{
"name": "page1",
"ppt": {
"src": "xxxx",
"width": 640,
"height": 360
}
},
{
"name": "page2",
"ppt": {
"src": "xxxx",
"width": 640,
"height": 360
}
}
],
"path": "/test"
}
```
### HTTP response [#http-response-1]
For details about all possible response status codes, see the [status code table](./index#status-codes).
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:**
```json
"status": 201,
"body":
{}
```
The response body is an empty JSON object.
If the status code is not `201`, the request fails. The response body includes a `message` field that describes the reason for the failure.
## Switch to a scene (PATCH) [#switch-to-a-scene-patch]
Call this API to switch scenes when there are multiple scenes or scene directories in the room.
### Prototype [#prototype-2]
* Method: `PATCH`
* Access point: `https://api.netless.link/v5/rooms/{uuid}/scene-state`
### Request header [#request-header-2]
Pass in the following parameters in the request header:
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | Required | An SDK token or room token with the `admin` role. To get an SDK token, you can:- Get a test-purpose SDK token from Agora Console. See [Get security credentials for your whiteboard project](/en/realtime-media/whiteboard/build/set-up-and-build-your-first-app/enable-whiteboard.md#get-security-credentials-for-your-whiteboard-project).
- Call the RESTful API. See [Generate an SDK token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
To get a room token, you can:- Call the RESTful API. See [Generate a room token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md#generate-a-room-token-post).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
|
| `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 [#request-path-2]
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](./room-management#create-a-room-post) or calling the [RESTful API to get room information](./room-management#get-room-information-get). |
### Request body [#request-body-1]
| Parameter | Data type | Required/Optional | Description |
| :---------- | :-------- | :---------------- | :------------------------------------------- |
| `scenePath` | string | Required | The path of the scene you want to switch to. |
### Request example [#request-example-2]
```bash
PATCH /v5/rooms/faexxxxx1947c/scene-state
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9TxxxxxYjc0
{
"scenePath": "/test/page1"
}
```
### HTTP response [#http-response-2]
For details about all possible response status codes, see the [status code table](./index#status-codes).
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:**
```json
"status": 201,
"body":
{
"currentScenePath": [
"test",
"page1"
]
}
```
**Description of parameters in the response:**
| Parameter | Data type | Description |
| :----------------- | :-------- | :------------------------------------------------------------------------------------------------------------------- |
| `currentScenePath` | array | The path of the current scene, which is an array consisting of the scene name and the corresponding scene directory. |
If the status code is not `201`, the request fails. The response body includes a `message` field that describes the reason for the failure.