Skip to main content

Agora Developer Center

Docs

Scene management

Get scene path list (GET)​

Call this API to get a list of scene paths in a room.

Prototype​

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

Request header​

Pass in the following parameters in the request header:

ParameterData typeRequired/OptionalDescription
tokenstringRequiredAn 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.
  • Call the RESTful API. See Generate an SDK token.
  • Use code samples. See Generate a token from your app server.
    • To get a room token, you can:
  • Call the RESTful API. See Generate a Room Token.
  • Use code samples. See Generate a token from your app server.
    • regionstringRequiredSpecifies 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.
  • gb-lon: London, England, 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:

    ParameterData typeRequired/OptionalDescription
    uuidstringRequiredThe 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.

    Query parameters​

    You can choose to pass in the following query parameters:

    ParameterData typeRequired/OptionalDescription
    sceneDirstringOptionalThe 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​


    _5
    GET /v5/rooms/faexxxxx47c/scenes?sceneDir=/test
    _5
    Host: api.netless.link
    _5
    region: us-sv
    _5
    token: NETLESSSDK_YWs9T3YtxxxxxYjc0
    _5
    Content-Type: application/json

    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.

    Response example


    _6
    "status": 200,
    _6
    "body":
    _6
    [
    _6
    "/test/cover",
    _6
    "/test/page1"
    _6
    ]

    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)​

    Call this API to add a scene.

    Prototype​

    • Method: POST
    • Access point: https://api.netless.link/v5/rooms/{uuid}/scenes

    Request header​

    Pass in the following parameters in the request header:

    ParameterData typeRequired/OptionalDescription
    tokenstringRequiredAn 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.
  • Call the RESTful API. See Generate an SDK token.
  • Use code samples. See Generate a token from your app server.
    • To get a room token, you can:
  • Call the RESTful API. See Generate a room token.
  • Use code samples. See Generate a token from your app server.
    • regionstringRequiredSpecifies 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.
  • gb-lon: London, England, 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:

    ParameterData typeRequired/OptionalDescription
    uuidstringRequiredThe 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​

    ParameterData typeRequired/OptionalDescription
    scenesarrayRequiredAn 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.
    • pathstringRequiredThe 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​


    _27
    POST /v5/rooms/a7e0xxxxxa69/scenes
    _27
    Host: api.netless.link
    _27
    region: us-sv
    _27
    Content-Type: application/json
    _27
    token: NETLESSSDK_YWs9QlxxxxxA0NzA5ZGM2MjRi
    _27
    _27
    {
    _27
    "scenes": [
    _27
    {
    _27
    "name": "page1",
    _27
    "ppt": {
    _27
    "src": "xxxx",
    _27
    "width": 640,
    _27
    "height": 360
    _27
    }
    _27
    },
    _27
    {
    _27
    "name": "page2",
    _27
    "ppt": {
    _27
    "src": "xxxx",
    _27
    "width": 640,
    _27
    "height": 360
    _27
    }
    _27
    }
    _27
    ],
    _27
    "path": "/test"
    _27
    }

    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:


    _3
    "status": 201,
    _3
    "body":
    _3
    {}

    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)​

    Call this API to switch scenes when there are multiple scenes or scene directories in the room.

    Prototype​

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

    Request header​

    Pass in the following parameters in the request header:

    ParameterData typeRequired/OptionalDescription
    tokenstringRequiredAn 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.
  • Call the RESTful API. See Generate an SDK token.
  • Use code samples. See Generate a token from your app server.
    • To get a room token, you can:
  • Call the RESTful API. See Generate a room token.
  • Use code samples. See Generate a token from your app server.
    • regionstringRequiredSpecifies 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.
  • gb-lon: London, England, 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:

    ParameterData typeRequired/OptionalDescription
    uuidstringRequiredThe 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​

    ParameterData typeRequired/OptionalDescription
    scenePathstringRequiredThe path of the scene you want to switch to.

    Request example​


    _9
    PATCH /v5/rooms/faexxxxx1947c/scene-state
    _9
    Host: api.netless.link
    _9
    region: us-sv
    _9
    Content-Type: application/json
    _9
    token: NETLESSSDK_YWs9TxxxxxYjc0
    _9
    _9
    {
    _9
    "scenePath": "/test/page1"
    _9
    }

    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:


    _8
    "status": 201,
    _8
    "body":
    _8
    {
    _8
    "currentScenePath": [
    _8
    "test",
    _8
    "page1"
    _8
    ]
    _8
    }

    Description of parameters in the response:

    ParameterData typeDescription
    currentScenePatharrayThe 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.

    Page Content