Cloud Recording

Recording task lifecycle and Agora-compatible endpoints.

Generated from the public REST API definitions

Version v1.1.0 · Updated 2026-10-26 · revision 1

Group overview

Generated at build time from the public REST API definition: tag recordings, 13 operations (out of 189). For authentication, envelope and pagination conventions see REST API overview.

Method	Path	Summary
`POST`	`/v1/apps/{appid}/cloud_recording/acquire`	Agora: acquire a recording resource
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start`	Agora: start cloud recording
`GET`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query`	Agora: query cloud recording
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop`	Agora: stop cloud recording
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout`	Agora: update layout
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update`	Update a recording session
`GET`	`/v1/recordings`	List recording tasks
`POST`	`/v1/recordings`	Start a recording task
`GET`	`/v1/recordings/{id}`	Get a recording task
`GET`	`/v1/recordings/{id}/files/{fileIndex}`	Download one recording file
`POST`	`/v1/recordings/{id}/files/{fileIndex}/playback-ticket`	Issue a short-lived playback ticket for one recording file
`POST`	`/v1/recordings/{id}/layout`	Update layout of a running recording
`POST`	`/v1/recordings/{id}/stop`	Stop a recording task

Operation details

POST `/v1/apps/{appid}/cloud_recording/acquire`

Agora: acquire a recording resource

Returns a single-use resourceId valid for 30 seconds; call start next.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`appid`	path	is	`string`	pattern ^[a-f0-9]{32}$

Request body

Field	Type	Required
`cname`	`string`	is
`uid`	`string`	is
`clientRequest`	`object`

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "scene": 0
  }
}

Response

Status codes	Description / schema
`200`	`{ resourceId }` — `AgoraRecordingResource`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/acquire" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"scene":0}}'

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start`

Agora: start cloud recording

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`appid`	path	is	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	is	`string`	length 0..128
`mode`	path	is	`enum(mix \| individual \| web)`

Request body

Field	Type	Required	Description
`cname`	`string`	is
`uid`	`string`	is
`clientRequest`	`object`		recordingConfig / storageConfig subset

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "recordingConfig": {
      "mixedVideoLayout": 1
    }
  }
}

Response

Status codes	Description / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, state } }` — `AgoraRecordingStart`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/mode/mix/start" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"recordingConfig":{"mixedVideoLayout":1}}}'

GET `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query`

Agora: query cloud recording

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`appid`	path	is	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	is	`string`	length 0..128
`sid`	path	is	`string`	length 0..128
`mode`	path	is	`enum(mix \| individual \| web)`

Response

Status codes	Description / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, status, fileList } }` — `AgoraRecordingQuery`

Example call

bash

curl -s -X GET "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/sid/$SID/mode/mix/query" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop`

Agora: stop cloud recording

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`appid`	path	is	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	is	`string`	length 0..128
`sid`	path	is	`string`	length 0..128
`mode`	path	is	`enum(mix \| individual \| web)`

Request body

Field	Type	Required	Description
`cname`	`string`
`uid`	`string`
`clientRequest`	`object`

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {}
}

Response

Status codes	Description / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, status, fileList } }` — `AgoraRecordingStop`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/sid/$SID/mode/mix/stop" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{}}'

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout`

Agora: update layout

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`appid`	path	is	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	is	`string`	length 0..128
`sid`	path	is	`string`	length 0..128
`mode`	path	is	`enum(mix \| individual \| web)`

Request body

Field	Type	Required	Description
`cname`	`string`
`uid`	`string`
`clientRequest`	`object`

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "mixedVideoLayout": 2
  }
}

Response

Status codes	Description / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, layout } }` — `AgoraRecordingLayout`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/sid/$SID/mode/mix/updateLayout" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"mixedVideoLayout":2}}'

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update`

Update a recording session

Changes the subscription list, pauses or resumes a web page recording, or re-points the CDN push of a running session. Only valid while the session is active.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`appid`	path	is	`string`	pattern ^[a-f0-9]{32}$
`resourceid`	path	is	`string`	length 0..128
`sid`	path	is	`string`	length 0..128
`mode`	path	is	`enum(mix \| individual \| web)`

Request body

Field	Type	Required	Description
`cname`	`string`	is	length 0..128
`uid`	`string`	is	length 0..64
`clientRequest`	`object{ streamSubscribe, webRecordingConfig, rtmpPublishConfig, storageConfig }`	is

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "streamSubscribe": {
      "audioUidList": {
        "subscribeAudioUids": [
          "string"
        ],
        "unsubscribeAudioUids": [
          "string"
        ]
      },
      "videoUidList": {
        "subscribeVideoUids": [
          "string"
        ],
        "unsubscribeVideoUids": [
          "string"
        ]
      }
    },
    "webRecordingConfig": {
      "onhold": true
    },
    "rtmpPublishConfig": {
      "outputs": [
        {
          "rtmpUrl": "string"
        }
      ]
    }
  }
}

Response

Status codes	Description / schema
`200`	the session was updated — `object{ resourceId, sid, serverResponse }`
`400`	Invalid parameter — `Error`
`401`	Missing/invalid credentials — `Error`
`403`	Banned or service not enabled — `Error`
`404`	Resource not found — `Error`
`415`	Content-Type must be application/json — `Error`
`429`	Quota exceeded — `Error`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/resourceid/sid/$SID/mode/mix/update" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"streamSubscribe":{"audioUidList":{"subscribeAudioUids":["string"],"unsubscribeAudioUids":["string"]},"videoUidList":{"subscribeVideoUids":["string"],"unsubscribeVideoUids":["string"]}},"webRecordingConfig":{"onhold":true},"rtmpPublishConfig":{"outputs":[{"rtmpUrl":"string"}]}}}'

GET `/v1/recordings`

List recording tasks

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Type	Description
`channelName`	query	`string`
`state`	query	`string`	comma separated
`limit`	query	`integer`	<= 200

Response

Status codes	Description / schema
`200`	`{ total, tasks }` — `RecordingTaskList`

Example call

bash

curl -s -X GET "$NIMEET_API_BASE/v1/recordings?channelName=weekly-sync&state=running&limit=50" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/recordings`

Start a recording task

Requires the recording service. Composite mode records the mixed room; individual records one file per publisher; web records a page-oriented layout.

Authentication: project credentials (Base64 of customerId:customerSecret)

Request body

Field	Type	Required
`channelName`	`string`	is
`mode`	`enum(composite \| individual \| web)`
`layout`	`object`
`subscribeAudioUids`	`array<integer>`
`subscribeVideoUids`	`array<integer>`
`maxDurationSeconds`	`integer`
`idempotencyKey`	`string`

json

{
  "channelName": "weekly-sync",
  "mode": "composite",
  "layout": {
    "preset": "grid"
  }
}

Response

Status codes	Description / schema
`202`	accepted — `RecordingTaskBody`
`403`	Banned or service not enabled — `Error`
`404`	Resource not found — `Error`
`429`	Quota exceeded — `Error`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"channelName":"weekly-sync","mode":"composite","layout":{"preset":"grid"}}'

GET `/v1/recordings/{id}`

Get a recording task

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`id`	path	is	`string`	length 0..128

Response

Status codes	Description / schema
`200`	task — `RecordingTaskBody`
`404`	Resource not found — `Error`

Example call

bash

curl -s -X GET "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

GET `/v1/recordings/{id}/files/{fileIndex}`

Download one recording file

Streams the stored artifact of a recording task. Tenant-scoped: the task is looked up inside the authenticated project, so another tenant id returns 404. Replaces the deprecated operator-only /internal/objects/{objectKey} surface (no tenant boundary, sunset 2027-01-31).

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`id`	path	is	`string`	length 0..128
`fileIndex`	path	is	`integer`	>= 0

Response

Status codes	Description / schema
`200`	recording file bytes
`404`	Resource not found — `Error`

Example call

bash

curl -s -X GET "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/files/1" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/recordings/{id}/files/{fileIndex}/playback-ticket`

Issue a short-lived playback ticket for one recording file

Browser players cannot attach Basic credentials to a <video> request, so a tenant-authenticated caller exchanges its credentials for a 10-minute HMAC ticket. The returned URL carries ?expires=&ticket= and the file route accepts it without project authentication (the signature covers task id, file index and expiry). Returns 503 when RECORDING_PLAYBACK_SECRET is not configured.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`id`	path	is	`string`	length 0..128
`fileIndex`	path	is	`integer`	>= 0

Response

Status codes	Description / schema
`200`	signed playback URL and its expiry — `object{ url, expiresAt }`
`401`	Missing/invalid credentials — `Error`
`404`	Resource not found — `Error`
`503`	playback signing is not configured on this deployment — `Error`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/files/1/playback-ticket" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/recordings/{id}/layout`

Update layout of a running recording

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`id`	path	is	`string`	length 0..128

Request body

Field	Type	Required	Description
`preset`	`enum(grid \| bestFit \| pip \| single)`
`canvasWidth`	`integer \| null`
`canvasHeight`	`integer \| null`
`backgroundColor`	`string \| null`

json

{
  "preset": "pip"
}

Response

Status codes	Description / schema
`200`	the task after the layout was applied — `RecordingTaskBody`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/layout" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"preset":"pip"}'

POST `/v1/recordings/{id}/stop`

Stop a recording task

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

Name	Location	Required	Type	Description
`id`	path	is	`string`	length 0..128

Response

Status codes	Description / schema
`200`	the stopped task (same shape as `GET /v1/recordings/{id}`) — `RecordingTaskBody`
`404`	Resource not found — `Error`

Example call

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/stop" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

Schemas used by this group

AgoraRecordingFile — object{ fileName, duration, size }

Field	Type	Required	Description
`fileName`	`string`	is
`duration`	`number`	is	seconds; 0 while the file is still being written
`size`	`number`	is	bytes; 0 while the file is still being written

AgoraRecordingLayout — object{ resourceId, sid, serverResponse }

Field	Type	Required
`resourceId`	`string`	is
`sid`	`string`	is
`serverResponse`	`object{ taskId, layout }`	is

AgoraRecordingQuery — object{ resourceId, sid, serverResponse }

Field	Type	Required
`resourceId`	`string`	is
`sid`	`string`	is
`serverResponse`	`object{ taskId, status, fileList, error }`	is

AgoraRecordingResource — object{ resourceId }

Field	Type	Required	Description
`resourceId`	`string`	is	single-use marker valid for 30 s; pass it to `start`

AgoraRecordingStart — object{ resourceId, sid, serverResponse }

Field	Type	Required	Description
`resourceId`	`string`	is
`sid`	`string`	is	our recording task id (Agora calls it `sid`)
`serverResponse`	`object{ taskId, state }`	is

AgoraRecordingStop — object{ resourceId, sid, serverResponse }

Field	Type	Required
`resourceId`	`string`	is
`sid`	`string`	is
`serverResponse`	`object{ taskId, status, fileList }`	is

Error — object{ code, message, reason, sdkCode, details }

Field	Type	Required	Description
`code`	`string`	is	stable machine code, see errors.json
`message`	`string`	is
`reason`	`string`
`sdkCode`	`integer`		Agora-aligned client error number
`details`	`object`

RecordingTaskBody — object

Field	Type	Required	Description
`id`	`string`
`channelName`	`string`
`mode`	`enum(composite \| individual \| web)`
`state`	`enum(starting \| running \| stopping \| stopped \| failed \| expired)`
`layout`	`object{ preset, canvasWidth, canvasHeight, backgroundColor }`
`files`	`array<object{ objectKey, url, format, durationSeconds, sizeBytes }>`
`usageSeconds`	`number`
`error`	`string \| null`
`startedAt`	`string \| null`
`endedAt`	`string \| null`

RecordingTaskList — object{ total, tasks }

Field	Type	Required	Description
`total`	`integer`	is
`tasks`	`array<object>`	is

Cloud Recording

Group overview

Operation details

POST /v1/apps/{appid}/cloud_recording/acquire

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start

GET /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update

GET /v1/recordings

POST /v1/recordings

GET /v1/recordings/{id}

GET /v1/recordings/{id}/files/{fileIndex}

POST /v1/recordings/{id}/files/{fileIndex}/playback-ticket

POST /v1/recordings/{id}/layout

POST /v1/recordings/{id}/stop

Schemas used by this group

POST `/v1/apps/{appid}/cloud_recording/acquire`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start`

GET `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update`

GET `/v1/recordings`

POST `/v1/recordings`

GET `/v1/recordings/{id}`

GET `/v1/recordings/{id}/files/{fileIndex}`

POST `/v1/recordings/{id}/files/{fileIndex}/playback-ticket`

POST `/v1/recordings/{id}/layout`

POST `/v1/recordings/{id}/stop`