REST API Overview and Conventions

Authentication, envelopes, pagination, errors, idempotency, request tracing and the product endpoint index.

Generated from the public REST API definitions

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

This page is the entry point to the REST API Reference. Every API table is generated at build time from the public REST API definition: the product groups below, and the methods / paths / parameters / request bodies / responses / curl on each group page, are rendered straight from the interface definition by a script — there is no hand-copied interface list.

Prerequisites and request example#

• Base URL: https://api.your-domain.example (an example value; replace it with your control-plane address).
• Authentication: server-side calls use Authorization: Basic base64(customerId:customerSecret); console calls use Authorization: Bearer <session>.
• Request headers: write requests must send Content-Type: application/json; include X-Request-Id to simplify troubleshooting.
• Response: a successful call returns the resource object; a failure returns the unified error envelope { code, message, reason, sdkCode, details? }.

curl -s https://api.your-domain.example/v1/tokens \
  -u "$CUSTOMER_ID:$CUSTOMER_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"channelName":"weekly-sync","uid":10001,"role":"host","ttlSeconds":3600}'

When to use REST and when to use an SDK#

Permission and credential boundaries#

What each group page contains#

• The operation index for that group (method / path / summary, clickable);
• For every operation: a parameter table (name/location/required/type/constraints), request body field table plus example, response table, and a copy-ready curl;
• The components.schemas used by that group (field tables expanded from the interface definition).

Relationship to other pages#

• Error envelope and error codes: full error-code table (generated from the errors interface definition).
• Callback (webhook) events: callback event reference (generated from the callbacks interface definition).
• End-to-end runnable scripts: the bundled examples scripts; see Quickstart for how to run them.

Next steps#

• REST API reference: complete endpoints, parameters and curl.
• Error codes: locate failures by code / HTTP status.
• FAQ: quotas, limits and troubleshooting.

Authentication

Project credentials（Basic）must stay on the server; browsers/mobile clients only hold { appId, rtcToken, rtcUid }。

Common conventions

• write operations（POST/PUT/PATCH）must carry Content-Type: application/json，otherwise returns 415 unsupported_media_type。
• list pagination uses page_no(0-based)and page_size（1..500，default 100)。
• failure responses use the unified { code, message, reason, sdkCode, details? }，for the complete error catalogue see Error codes。
• every response echoes X-Request-Id，include it first when troubleshooting.
• Agora-compatible paths use the /dev/v1/*、/v1/apps/{appid}/cloud_recording/*、/v1/projects/{appid}/fls/* prefix, the response uses Agora's success/data、{resourceId,sid,serverResponse} envelope.
• Idempotency: duplicate submissions of create endpoints may return the same resource; query the current state before retrying a failed write (see Error codes 's 409 Description）。

Product groups and operation index

189 operations, 15 product groups, Each group has its own page:

Schema dictionary

components.schemas declarations and reference counts:

• Referenced by operations: 68
• Total declarations (including aliases)：58

Each group page also expands the schemas used by that group.