# Update task settings (/en/api-reference/api-ref/cloud-recording/update)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Updates the settings of an active cloud recording task.

- OpenAPI: /openapi/cloud-recording/cloud-recording.en.yaml
- Operation ID: update-cloud-recording
- Method: POST
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update
- Endpoint: https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update

## Servers

- https://api.sd-rtn.com

After starting a recording task, call this endpoint to update the subscription list, pause or resume web page recording, or update the CDN push address.


:::info[Note]
- This endpoint is only valid within an active recording session. If the recording was not started successfully or has already ended, the request returns `404`.
- If you need to call `update` multiple times in succession, wait for the previous `update` response before sending the next request to avoid unexpected results.
:::

## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `Content-Type` (header, optional, string) - `application/json`.
  - Default: `application/json`
- `appid` (path, required, string) - The App ID of your project.
- For web page recording mode, enter the App ID for which the cloud recording service is enabled.
- For individual and composite recording modes, use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
- `resourceid` (path, required, string) - The resource ID obtained from the `acquire` endpoint.
- `sid` (path, required, string) - The recording ID obtained from the `start` endpoint.
- `mode` (path, required, string) - The recording mode:
- `individual`: Individual recording mode.
- `mix`: Composite recording mode.
- `web`: Web page recording mode.
  - Allowed: `individual` | `mix` | `web`

## Request body

- `cname` (string, required) - The name of the channel to record. Must match the `cname` used in the `acquire` request.
The name of the channel being recorded.
- `uid` (string, required) - The UID used by the cloud recording service in the channel. Must match the `uid` used in the `acquire` request.
The UID used by the cloud recording service in the RTC channel.
- `clientRequest` (object, required)
  - `clientRequest.streamSubscribe` (object) - Updates the subscription lists. Only applicable in individual recording and composite recording modes.
    - `clientRequest.streamSubscribe.audioUidList` (object) - The audio subscription list. Only applicable when `streamTypes` is `0` or `2`.
      - `clientRequest.streamSubscribe.audioUidList.subscribeAudioUids` (array) - Audio streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeAudioUids.
        - `clientRequest.streamSubscribe.audioUidList.subscribeAudioUids.items` (string)
      - `clientRequest.streamSubscribe.audioUidList.unsubscribeAudioUids` (array) - Video streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with `subscribeVideoUids`.
        - `clientRequest.streamSubscribe.audioUidList.unsubscribeAudioUids.items` (string)
    - `clientRequest.streamSubscribe.videoUidList` (object) - The video subscription list. Only applicable when `streamTypes` is `1` or `2`.
      - `clientRequest.streamSubscribe.videoUidList.subscribeVideoUids` (array) - Video streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with `subscribeVideoUids`.
        - `clientRequest.streamSubscribe.videoUidList.subscribeVideoUids.items` (string)
      - `clientRequest.streamSubscribe.videoUidList.unsubscribeVideoUids` (array) - Video streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with `subscribeVideoUids`.
        - `clientRequest.streamSubscribe.videoUidList.unsubscribeVideoUids.items` (string)
  - `clientRequest.webRecordingConfig` (object) - Updates web page recording settings. Only applicable in web page recording mode.
    - `clientRequest.webRecordingConfig.onhold` (boolean) - Whether to pause web page recording. `true` pauses recording and file generation. `false` resumes recording.
      - Default: `false`
  - `clientRequest.rtmpPublishConfig` (object) - Updates the CDN push configuration. Only applicable when pushing web page recording to CDN.
    - `clientRequest.rtmpPublishConfig.outputs` (array)
      - `clientRequest.rtmpPublishConfig.outputs.items` (object)
        - `clientRequest.rtmpPublishConfig.outputs.items.rtmpUrl` (string) - The CDN URL to push the stream to. Only RTMP and RTMPS protocols are supported. A maximum of one stream can be pushed to CDN at a time.
  - `clientRequest.storageConfig` (object) - Updates the third-party cloud storage configuration. Use this to refresh an expiring `stsToken`.
    - `clientRequest.storageConfig.vendor` (integer, required) - Third-party cloud storage platform:
- `1`: Amazon S3
- `2`: Alibaba Cloud
- `3`: Tencent Cloud
- `5`: Microsoft Azure
- `6`: Google Cloud
- `7`: Huawei Cloud
- `8`: Baidu IntelligentCloud
- `11`: S3-compatible storage. Specify the domain name in `extensionParams.endpoint`.
    - `clientRequest.storageConfig.region` (integer, required) - The region of the third-party cloud storage.

      :::info[Note]
      To ensure upload success and real-time performance, the cloud storage region must match the region of the server where you initiate the request. See [Third-party cloud storage regions](/en/realtime-media/cloud-recording/reference/region-vendor).
      :::
    - `clientRequest.storageConfig.bucket` (string, required) - The cloud storage bucket name. Must comply with the naming rules of the corresponding cloud storage service.
    - `clientRequest.storageConfig.accessKey` (string, required) - The access key for the third-party cloud storage.
    - `clientRequest.storageConfig.secretKey` (string, required) - The secret key for the third-party cloud storage.
    - `clientRequest.storageConfig.stsToken` (string) - A temporary security token issued by the cloud provider's Security Token Service (STS), granting limited access to cloud storage resources.

 Currently supported only for Amazon S3 (`1`), Alibaba Cloud (`2`), and Tencent Cloud (`3`).
    - `clientRequest.storageConfig.stsExpiration` (integer) - The `stsToken` expiration time as a Unix timestamp in seconds.
- Use Uint64 storage to avoid timestamp overflow.
- Set the longest possible validity period when applying the token. The minimum validity period is 4 hours.
- If the recording task runs longer than 1 hour, reapply a new `stsToken` every 60 minutes and call `update` again to refresh the `storageConfig`.
    - `clientRequest.storageConfig.fileNamePrefix` (array) - The storage path prefix for recorded files. For example, setting `["directory1","directory2"]` results in a file name prefix of `directory1/directory2/`. The total prefix length, including slashes, cannot exceed 128 characters. Supported characters: lowercase letters `a-z`, uppercase letters `A-Z`, digits `0-9`.
      - `clientRequest.storageConfig.fileNamePrefix.items` (string)
    - `clientRequest.storageConfig.extensionParams` (object) - Encryption and tagging settings applied to uploaded recording files by the cloud storage service.
      - `clientRequest.storageConfig.extensionParams.sse` (string, required) - The encryption mode for uploaded files. Applicable to Amazon S3 only. See the Amazon S3 documentation.
- `kms`: KMS encryption.
- `aes256`: AES256 encryption.
      - `clientRequest.storageConfig.extensionParams.tag` (string, required) - Tag content applied to uploaded files. Applicable to Alibaba Cloud and Amazon S3 only.
      - `clientRequest.storageConfig.extensionParams.endpoint` (string) - The domain name for S3 protocol cloud storage. This field is required when you set `vendor` to `11`.

### Request body example

```json
{
  "cname": "httpClient463224",
  "uid": "527841",
  "clientRequest": {
    "streamSubscribe": {
      "audioUidList": {
        "subscribeAudioUids": [
          "#allstream#"
        ]
      },
      "videoUidList": {
        "unsubscribeVideoUids": [
          "444",
          "555",
          "666"
        ]
      }
    }
  }
}
```

## Request examples

### curl

```bash
curl --request POST \
    --url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update \
    --header 'Authorization: Basic <credentials>' \
    --header 'Content-Type: application/json' \
    --data '{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
      "streamSubscribe": {
        "audioUidList": {
          "subscribeAudioUids": ["#allstream#"]
        },
        "videoUidList": {
          "unsubscribeVideoUids": ["444", "555", "666"]
        }
      }
    }
  }'
```

### Python

```python
import requests
  import json

  url = "https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update"
  headers = {
      "Authorization": "Basic <credentials>",
      "Content-Type": "application/json"
  }

  data = {
      "cname": "httpClient463224",
      "uid": "527841",
      "clientRequest": {
          "streamSubscribe": {
              "audioUidList": {
                  "subscribeAudioUids": ["#allstream#"]
              },
              "videoUidList": {
                  "unsubscribeVideoUids": ["444", "555", "666"]
              }
          }
      }
  }

  response = requests.post(url, headers=headers, data=json.dumps(data))

  print(response.status_code)
  print(response.json())
```

### Node.js

```javascript
const axios = require('axios');

  const url = 'https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update';
  const headers = {
    'Authorization': 'Basic <credentials>',
    'Content-Type': 'application/json'
  };

  const data = {
    cname: "httpClient463224",
    uid: "527841",
    clientRequest: {
      streamSubscribe: {
        audioUidList: {
          subscribeAudioUids: ["#allstream#"]
        },
        videoUidList: {
          unsubscribeVideoUids: ["444", "555", "666"]
        }
      }
    }
  };

  axios.post(url, data, { headers })
    .then(response => {
      console.log('Status:', response.status);
      console.log('Data:', response.data);
    })
    .catch(error => {
      console.error('Error:', error.response ? error.response.data : error.message);
    });
```


### Response

- If the returned status code is `200`, the request was successful.

- If the returned status code is not `200`, the request failed. See [Response status codes](/en/api-reference/api-ref/cloud-recording/status-codes) for troubleshooting.


## Responses

### 200

The request succeeded.

- `resourceId` (string) - The cloud recording resource ID. Valid for five minutes; re-request from `acquire` if expired.

The resource ID used by cloud recording.
- `sid` (string) - The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.

The recording ID, identifying the current recording session.
- `cname` (string) - The name of the channel to be recorded.

The name of the channel being recorded.
- `uid` (string) - The UID used by the cloud recording service in the RTC channel.
### default

The request failed. If the HTTP status code is not `200`, see the Cloud Recording response status codes for troubleshooting.

No schema.

## Response examples

### 200

```json
{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string"
}
```

### Response example

```json
{
    "code": 404,
    "reason": "failed to find worker"
  }
```