# Screenshot management (/en/api-reference/api-ref/whiteboard/screenshots)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
The screenshot-management feature is implemented by Interactive Whiteboard. You can take screenshots for a single scene or a scene directory, generate images in PNG format, and upload them to a third-party cloud storage space.
Before calling the REST API for screenshot management, ensure that:
* You have created a third-party cloud storage account and a storage space under that account. Agora supports only [Amazon Simple Storage Service (Amazon S3)](https://aws.amazon.com/s3/?nc1=h_ls) now.
* You have enabled the screenshot feature and configured storage settings in Agora Console. See [Enable whitebaord server-side features](/en/realtime-media/whiteboard/build/set-up-and-build-your-first-app/enable-whiteboard.md#enable-whiteboard-server-side-features).
## Screenshot a scene [#screenshot-a-scene]
Call this API to take screenshots for a single scene.
This backend screenshot API is deprecated. Use the frontend API, [`screenshotToCanvasAsync`](https://api-ref.agora.io/en/interactive-whiteboard-sdk/web/2.x/interfaces/displayer.html#screenshottocanvas), instead.
### Prototype [#prototype]
* Method: `POST`
* Access point: `https://api.netless.link/v5/rooms/{uuid}/screenshots`
### 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 REST 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).
To get a room token, you can:- Call the REST 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 [REST API to create a room](./room-management#create-a-room-post) or calling the [REST API to get room information](./room-management#get-room-information-get). |
### Request body [#request-body]
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | :---------------------------------------------------------------------------------------------------------------- |
| `width` | number | Required | The width of the screenshot in pixels. |
| `height` | number | Required | The height of the screenshot in pixels. |
| `path` | string | Optional | The path to the scene, which starts with `/`. If you do not set this parameter, the default path `/init` is used. |
### Request example [#request-example]
```bash
POST /v5/rooms/a7e04xxxxx7d1eca69/screenshots
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9xxxxxxzA5ZGM2MjRi
{
"width": 640,
"height": 480
}
```
### HTTP response [#http-response]
For details about all possible response status codes, see the [status code table](overview#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":
{
"url": "https://white-cover.oss-cn-hangzhou.aliyuncs.com/room_cover/2811/a7exxxxca69undefined.png",
"key": "room_cover/2811/a7exxxxxca69undefined.png",
"bucket": "white-cover",
"region": "oss-cn-hangzhou"
}
```
**Description of parameters in the response:**
| Parameter | Data type | Description |
| :-------- | :-------- | :----------------------------------------------------------- |
| `url` | string | The URL of the screenshot. |
| `key` | string | The filename of the screenshot in the storage space. |
| `bucket` | string | The name of the storage space where the screenshot is saved. |
| `region` | string | The region where the storage space is located. |
If the status code is not `201`, the request fails. The response body includes a `message` field that describes the reason for the failure.
## Screenshot a scene directory [#screenshot-a-scene-directory]
Call this API to take screenshots for a scene directory.
This backend screenshot API is deprecated. Use the frontend API, [`screenshotToCanvasAsync`](https://api-ref.agora.io/en/interactive-whiteboard-sdk/web/2.x/interfaces/displayer.html#screenshottocanvas), instead.
### Prototype [#prototype-1]
* Method: `POST`
* Access point: `https://api.netless.link/v5/rooms/{uuid}/screenshot-list`
### 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 REST 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 REST 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 [REST API to create a room](./room-management#create-a-room-post) or calling the [REST API to get room information](./room-management#get-room-information-get). |
### Request body [#request-body-1]
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `width` | number | Required | The width of the screenshot in pixels. |
| `height` | number | Required | The height of the screenshot in pixels. |
| `path` | string | Optional | The path to the scene directory, which starts with `/`. If you do not set this parameter , the current scene directory is used. |
### Request example [#request-example-1]
```bash
POST /v5/rooms/faed3130727911ebaea37759ee91947c/screenshot-list
Host: api.netless.link
region: us-sv
token: NETLESSSDK_YWsxxxxxxYjc0
Content-Type: application/json
{
"width": 640,
"height": 480,
"path": "/test"
}
```
### HTTP response [#http-response-1]
For details about all possible response status codes, see the [status code table](overview#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":
[
{
"url": "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/room_cover/2811/faxxxxx47c/test/cover.png",
"key": "room_cover/2811/faxxxxx47c/test/cover.png",
"bucket": "docs-test-xxx",
"region": "oss-cn-hangzhou"
},
{
"url": "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/room_cover/2811/faxxxxx47c/test/page1.png",
"key": "room_cover/2811/faxxxxx47c/test/page1.png",
"bucket": "docs-test-xxx",
"region": "oss-cn-hangzhou"
}
]
```
The response body is an array of the screenshot information for each scene. Every member in the array contains the following parameters:
| Parameter | Data type | Description |
| :-------- | :-------- | :----------------------------------------------------------- |
| `url` | string | The URL of the screenshot. |
| `key` | string | The filename of the screenshot in the storage space. |
| `bucket` | string | The name of the storage space where the screenshot is saved. |
| `region` | string | The region where the storage space is located. |
If the status code is not `201`, the request fails. The response body includes a `message` field that describes the reason for the failure.