Channel Management REST API

In addition to the SDK that you integrate into the app client, Agora provides a set of simple, secure, and reliable server-side RESTful APIs to manage real-time audio and video channels.

This page provides detailed documentation for the Agora Channel Management RESTful APIs.

Key features and use-cases

Authorization

Domain

All requests are sent to the following domain name: api.agora.io.

For example, after implementing basic HTTP authentication, use the following code to send a simple request to obtain the total number of channels and the number of users in each channel:

public class Base64Encoding {

    public static void main(String[] args) throws IOException, InterruptedException {

        // Customer ID
        // Set the AGORA_CUSTOMER_KEY environment variable
        final String customerKey = System.getenv("AGORA_CUSTOMER_KEY");
        // Customer key
        // Set the AGORA_CUSTOMER_SECRET environment variable
        final String customerSecret = System.getenv("AGORA_CUSTOMER_SECRET");

        // Set the AGORA_APP_ID variable
        final String appid = System.getenv("AGORA_APP_ID");

        // Concatenate the customer ID and customer secret and encode them using base64
        String plainCredentials = customerKey + ":" + customerSecret;
        String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));
        // Create the authorization header
        String authorizationHeader = "Basic :" + base64Credentials

        HttpClient client = HttpClient.newHttpClient();

        // Create an HTTP request object
        HttpRequest request = HttpRequest.newBuilder()
               .uri(URI.create("https://api.sd-rtn.com/dev/v1/channel/" + appid))
               .GET()
               .header("Authorization", authorizationHeader)
               .header("Content-Type", "application/json")
               .build();
        // Send an HTTP request
        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
        // Add the subsequent processing logic for the response content
   }
}

package main

  "encoding/base64"
  "fmt"
  "net/http"
  "os"
  "io/ioutil"
)

func main() {
  // Retrieve environment variables
  customerKey := os.Getenv("AGORA_CUSTOMER_KEY")
  customerSecret := os.Getenv("AGORA_CUSTOMER_SECRET")
  appID := os.Getenv("AGORA_APP_ID")

  if customerKey == "" || customerSecret == "" || appID == "" {
    fmt.Println("Environment variables AGORA_CUSTOMER_KEY, AGORA_CUSTOMER_SECRET, and AGORA_APP_ID must be set.")
    return
  }

  // Concatenate the customer ID and secret, then encode them using Base64
  plainCredentials := customerKey + ":" + customerSecret
  base64Credentials := base64.StdEncoding.EncodeToString([]byte(plainCredentials))

  // Create the authorization header
  authorizationHeader := "Basic " + base64Credentials

  // Build the request
  req, err := http.NewRequest("GET", "https://api.sd-rtn.com/dev/v1/channel/"+appID, nil)
  if err != nil {
    fmt.Println("Error creating request:", err)
    return
  }

  // Add headers
  req.Header.Add("Authorization", authorizationHeader)
  req.Header.Add("Content-Type", "application/json")

  // Create an HTTP client and send the request
  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error sending request:", err)
    return
  }
  defer resp.Body.Close()

  // Read the response body
  body, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    fmt.Println("Error reading response body:", err)
    return
  }

  // Print the response body
  fmt.Println(string(body))

  // Add any subsequent processing logic for the response content here
}

Use the channel management RESTful API along with the Agora Notifications service for reliable and effective channel management and status synchronization.

Call frequency limit

For each Agora account (not each App ID), the maximum call frequency of every online channel statistics query API is 20 queries per second. The maximum call frequency of every other API is 10 queries per second. If you are frequency limited when calling the APIs, see How can I avoid being frequency limited when calling Agora Server RESTful APIs to optimize API call frequency.

Response status codes

For a description of the response status codes, refer to Response status codes.

Authentication

The Content-Type field in all HTTP request headers is application/json. All requests and responses are in JSON format. All request URLs and request bodies are case-sensitive.

The Agora Channel Management RESTful APIs only support HTTPS. Before sending HTTP requests, you must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and pass the credential to the Authorization field in the HTTP request header. See RESTful authentication for details.

Call the API

This page explains the structure of the channel management RESTful API and how to call it correctly.

Prerequisites

Before calling the API, make sure you have the following:

• An Agora app ID
• Customer ID
• Customer key

Request URL

Following is a sample request URL:

https://api.agora.io/dev/v1/kicking-rule

• https: The communication protocol. Agora uses HTTPS.
• api.agora.io: The domain name of the Agora server.
• dev/v1/kicking-rule: The resource path, including the API version and the resource name.

The above example is for reference only. Refer to the documentation of the API you want to call, select the method (GET, POST, PUT, PATCH, DELETE) in the code source file or debug application, and then configure the actual request URL according to your needs. The request URL is case-sensitive.

Request structure

A request consists of two parts: The request header and the request body.

The following example shows how to create a privilege banning rule by sending a POST request containing the app ID, channel name, user ID, user IP, ban duration, and the privilege list to the specified API address:

curl --location --request POST 'https://api.agora.io/dev/v1/kicking-rule' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <http_basic_auth>' \
--data '{
  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
  "cname": "channel1",
  "uid": 589517928,
  "ip": "123",
  "time": 60,
  "privileges": [
    "join_channel"
  ]
}'

Request header

The request header contains the following information needed to process the request:

• Accept: Tells the server what types of responses the client can handle, such as application/json.
• Authorization: The Agora RESTful API requires HTTP authentication. Every time you send an HTTP request, fill in the Authorization field in the request header. See RESTful authentication for details.
• Content-Type: Specifies the type of the request body, such as application/json.

Request body (optional)

The request body contains the information to be sent to the server. For example, to create a new rule to ban user privileges, include the relevant information, such as the app ID, channel name, user ID, user IP, ban duration, and the banned privileges. The request body is case-sensitive.

Response

After you send the request, the Agora server sends a response that includes a response status code and a response body. The channel management RESTful API does not have a response header.

Response status code

The HTTP response status code can be one of the following:

• 200: The request is successful.
• Other than 200: Refer to Response status codes to troubleshoot the problem.

Response body

The response body contains the information returned by the server. For example, the response body of creating a banning rule includes the request status and the rule ID.

The following is a response example for creating a banning rule:

{
  "status": "success",
  "id": 1953
}

Error handling

If you encounter a problem, use developer tools to view the request and response, and troubleshoot based on the response status code. If the problem persists, contact technical support.

Query channel list

GET https://api.agora.io/dev/v1/channel/{appid}

Use this endpoint to get the list of all channels under a specified project. The channel list is returned by page; specify the page number and page size in the request URL.

Request

The request URL and request body is case-sensitive. All requests must use HTTPS.

Request header

• Content-Type: application/json
• The request header must contain the Authorization field. For details, see RESTful authentication.

Path parameters

Query parameters

Response

A 200 status code indicates success. The response body contains the following parameters:

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

Authorization

This endpoint requires Basic authentication.

Request example

Test this request in Postman or use one of the following code examples:

curl --request GET \
  --url 'https://api.sd-rtn.com/dev/v1/channel/<appid>?page_no=0&page_size=100' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'

const http = require('http');

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/channel/<appid>?page_no=0&page_size=100',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    Accept: 'application/json'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

conn = http.client.HTTPConnection("api.sd-rtn.com")

headers = {
    'Authorization': "Basic <your_base64_encoded_credentials>",
    'Accept': "application/json"
}

conn.request("GET", "/dev/v1/channel/<appid>?page_no=0&page_size=100", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response example

{
  "success": true,
  "data": {
    "channels": [
      {
        "channel_name": "lkj144",
        "user_count": 3
      }
    ],
    "total_size": 1
  }
}

Query host list

GET https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}/hosts_only

Use this endpoint to get the list of hosts in a specified channel. This endpoint is only available in the LIVE_BROADCASTING profile (mode = 2); all users in the channel must use the same profile, otherwise query results may be inaccurate.

Request

The request URL and request body is case-sensitive. All requests must use HTTPS.

Request header

• Content-Type: application/json
• The request header must contain the Authorization field. For details, see RESTful authentication.

Path parameters

Response

A 200 status code indicates success. The response body contains the following parameters:

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

Reference

Synchronizing host online status

To synchronize the online status of hosts, you can use this endpoint or the query user status endpoint. This endpoint requires a lower call frequency and offers higher efficiency, so Agora recommends it for this purpose.

Authorization

This endpoint requires Basic authentication.

Request example

curl --request GET \
  --url https://api.sd-rtn.com/dev/v1/channel/user/<appid>/<channelName>/hosts_only \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'

const https = require('https');

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/channel/user/<appid>/<channelName>/hosts_only',
  headers: {
    Accept: 'application/json',
    Authorization: 'Basic <your_base64_encoded_credentials>'
  }
};

const req = https.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

conn = http.client.HTTPSConnection("api.sd-rtn.com")

headers = {
    'Accept': "application/json",
    'Authorization': "Basic <your_base64_encoded_credentials>"
}

conn.request("GET", "/dev/v1/channel/user/<appid>/<channelName>/hosts_only", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response example

{
  "success": true,
  "data": {
    "channel_exist": true,
    "mode": 2,
    "broadcasters": [
      574332,
      1347839
    ]
  }
}

Query user list

GET https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}

Use this endpoint to get the list of all users in a specified channel. All users in the channel must use the same channel profile; otherwise, the query results may be inaccurate.

The returned list differs based on the channel profile:

• COMMUNICATION profile: Returns the list of all users in the channel.
• LIVE_BROADCASTING profile: Returns the list of all hosts and audience members in the channel.

Request

The request URL and request body is case-sensitive. All requests must use HTTPS.

Request header

• Content-Type: application/json
• The request header must contain the Authorization field. For details, see RESTful authentication.

Path parameters

Query parameters

Response

A 200 status code indicates success. The response body contains the following parameters:

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

Reference

Synchronizing channel online statistics

To synchronize online channel statistics, you can use this endpoint or the query user status endpoint. This endpoint requires a lower call frequency and offers higher efficiency, so Agora recommends it for this purpose.

Authorization

This endpoint requires Basic authentication.

Request example

Test this request in Postman or use one of the following code examples:

curl --request GET \
  --url https://api.sd-rtn.com/dev/v1/channel/user/<appid>/<channelName> \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'

const https = require('https');

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/channel/user/<appid>/<channelName>',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    Accept: 'application/json'
  }
};

const req = https.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

conn = http.client.HTTPSConnection("api.sd-rtn.com")

headers = {
    'Authorization': "Basic <your_base64_encoded_credentials>",
    'Accept': "application/json"
}

conn.request("GET", "/dev/v1/channel/user/<appid>/<channelName>", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response example

In COMMUNICATION profile:

{
  "success": true,
  "data": {
    "channel_exist": true,
    "mode": 1,
    "total": 1,
    "users": [
      906218805
    ]
  }
}

In LIVE_BROADCASTING profile:

{
  "success": true,
  "data": {
    "channel_exist": true,
    "mode": 2,
    "broadcasters": [
      2206227541,
      2845863044
    ],
    "audience": [
      906219905
    ],
    "audience_total": 1
  }
}

Query user status

GET https://api.agora.io/dev/v1/channel/user/property/{appid}/{uid}/{channelName}

Use this endpoint to get the status of a specified user. It checks whether the user is in the specified channel and, if present, returns the user's role and the time they joined.

Request

The request URL and request body is case-sensitive. All requests must use HTTPS.

Request header

• Content-Type: application/json
• The request header must contain the Authorization field. For details, see RESTful authentication.

Path parameters

Response

A 200 status code indicates success. The response body contains the following parameters:

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

Authorization

This endpoint requires Basic authentication.

Request example

Test this request in Postman or use one of the following code examples:

curl --request GET \
  --url https://api.sd-rtn.com/dev/v1/channel/user/property/<appid>/<uid>/<channelName> \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'

const https = require('https');

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/channel/user/property/<appid>/<uid>/<channelName>',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    Accept: 'application/json'
  }
};

const req = https.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

conn = http.client.HTTPSConnection("api.sd-rtn.com")

headers = {
    'Authorization': "Basic <your_base64_encoded_credentials>",
    'Accept': "application/json"
}

conn.request("GET", "/dev/v1/channel/user/property/<appid>/<uid>/<channelName>", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response example

{
  "success": true,
  "data": {
    "join": 1640330382,
    "uid": 2845863044,
    "in_channel": true,
    "platform": 7,
    "role": 2
  }
}

Manage user privileges

This page illustrates the usage of the privilege banning API, including usage principles, applicable use-cases, inapplicable use-cases, and best practices for the exception handling.

For the API reference, see Create rule.

Usage principles

Follow these principles when using the API:

• Prevent the main business processes from relying too heavily on the privilege banning API.
• Prevent a RESTful call failure from affecting the main business processes.

Applicable use-cases

Ban violating users

Revoke the user's right to join the channel based on UID: Set privileges to join_channel, fill in uid, leave cname and ip blank, and set time to a value other than 0.

For example, when it is impossible to completely ban a violating user through your business signaling, you can ban them with this API by their UID.

Note that the banning API can be used as a fallback for your business signaling system, but you should consider whether there is a need to unban. Unbanning users is usually not integrated into the main service process to prevent possible call failures from affecting its operation.

• Correct usage example: A user files a complaint and their account is manually unbanned.
• Incorrect usage example: A user is automatically unbanned the next time they join the channel. This might result in the user being unable to join because of an API call failure.

Ban user audio and video privileges

Ban the user's audio and video streaming privileges based on UID: Set privileges to publish_audio or publish_video, fill in uid, leave cname and ip blank, and set time to a value other than 0.

For example, you can prevent a microphone from being used after it was left unattended by the streaming user.

Note that banning a user's streaming privileges through this API is a dangerous operation. It should be used as a backup measure after the user was notified of a failure to disconnect.

Take into full consideration the impact that a delay or failure to unban might have on the user's ability to use the microphone again, and set the ban time to be as short as possible.

Kick a user out of a channel

Kick the user out of the channel based on the channel name and UID. This means taking the user offline, after which they can log in again. Set privileges to join_channel, fill in cname and uid, leave ip blank, and set time to 0.

For example, if the host logs in from 2 devices simultaneously, these two devices will stream with the same uid, causing an exception. This API can be used to kick both devices offline, after which one of them can reconnect.

This API can be used as a backup if the leave channel signal sent by your own business server is invalid.

Note that a one-time kick with time set to 0 is a safer way to use this API. When the kick request reaches the edge node, if the SDK is disconnected from the edge node, the one-time kick will fail. If you find that the SDK is reconnected to the edge node after kicking the user, you can call this API again.

Disband a channel

When streaming ends, kick all users out of the channel by the channel name: set privileges to join_channel, fill in cname, leave uid and ip blank, and set time to 0.

Use this API to disband a channel. Set time to the time that the channel should not be restarted.

In this use-case, use your own signaling to notify the SDK to call leave channel after the streaming ends. If the business signaling cannot meet the needs, you can use forced disbanding as a fallback. If you rely entirely on RESTful requests, the impact caused by request failures might be too heavy.

If the channel will not be reused, you can set the ban for a longer period of time. If the channel will be reused after a certain period, make sure that the end time of the channel ban is not later than the next channel creation time. If the channel will be reused in an unknown period of time, it is recommended to kick the user from the channel or set the ban time to 1 minute.

It is not recommended to ban for a longer time and call the unbanning API when the channel starts. If unbanning fails, the users will not be able to join the channel.

Ban illegal IPs

Prevent the user from joining a channel based on IP: Set privileges to join_channel, fill in ip, leave cname and uid blank, and set time to a value other than 0.

For example, when a business is attacked and the IP of the attack source is identified, the ip field can be used to ban it.

Note that using the IP as the banning rule may accidentally affect other users, such as when multiple people share it.

Non-applicable use-cases

The following table summarizes the use-cases where this API should not be used and provides the reasons why.

Best practices for handling call exceptions

• Timeout settings

  It is recommended to set the client request timeout to a value of more than 20s (minimum 5s) to mitigate network fluctuations. When retrying a timed-out request, increase the timeout accordingly to improve the request success rate.

• Retry the request

  Decide whether to retry the request after failure and determine the number of retries based on your own business logic.

  When a request returns an error code greater than or equal to 500 or the request times out, you can continue to retry and increase the waiting interval between multiple retries in a gradual manner.

Query Agora Notifications IP addresses

GET https://api.agora.io/v2/ncs/ip

Use this endpoint to retrieve the IP addresses of the Agora Notifications server. If your server is behind a firewall, add these IP addresses to your allowlist to receive channel event notifications.

Request

The request URL and request body is case-sensitive. All requests must use HTTPS.

Request header

• Content-Type: application/json
• The request header must contain the Authorization field. For details, see RESTful authentication.

Response

A 200 status code indicates success. The response body contains the following parameters:

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

Authorization

This endpoint requires Basic authentication.

Request example

Use one of the following code examples to test this request:

curl --request GET \
  --url https://api.sd-rtn.com/v2/ncs/ip \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'

const https = require('https');

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/v2/ncs/ip',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    Accept: 'application/json'
  }
};

const req = https.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

conn = http.client.HTTPSConnection("api.sd-rtn.com")

headers = {
    'Authorization': "Basic <your_base64_encoded_credentials>",
    'Accept': "application/json"
}

conn.request("GET", "/v2/ncs/ip", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response example

{
  "data": {
    "service": {
      "hosts": [
        {
          "primaryIP": "xxx.xxx.xxx.xxx"
        },
        {
          "primaryIP": "xxx.xxx.xxx.xxx"
        }
      ]
    }
  }
}

Response status codes

This page describes all response status codes returned when calling the channel management RESTful API.

If the status code is 200, the request is successful. If not, troubleshoot the problem based on the message and reason fields that may appear in the corresponding response body.

For example, when a request fails, you might receive the following response:

# 400 Bad Request
{
  "message": "invalid appid"
}

Status codes

The following table summarizes all response status codes, their meanings, and recommended actions:

Troubleshooting example

A call to create a privilege banning rule returns 400 Bad Request and the message field value is invalid appid.

This means that the App ID is invalid and the rule creation has failed. Obtain the App ID in Agora Console and call the API again.