Overview

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	Description	Typical application scenarios
Manage user privileges	Includes removing specified users from channels and preventing them from sending audio and video streams.	Unauthorized users appear in a live broadcast. Users disrupt the room during a live broadcast. The signaling message sent to the client is hijacked. The user is offline abnormally, which interferes with timely user list updates.
Query channel information	Query the list of online channels, users in a channel, and the status of a specified user.	In a scenario where the number of concurrent channels is not large, directly query the channel list to sync the channel status. In a scenario where real-time sync performance is not required, query and sync the user list and status in the channel.

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.

All requests are sent to the following domain name: api.agora.io. For example, after implementing basic HTTP authentication, add the following code to send a simple request to obtain the total number of channels and the number of users in each channel:

_38

public class Base64Encoding {

_38

_38

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

_38

_38

// Customer ID

_38

// Set the AGORA_CUSTOMER_KEY environment variable

_38

final String customerKey = System.getenv("AGORA_CUSTOMER_KEY");

_38

// Customer key

_38

// Set the AGORA_CUSTOMER_SECRET environment variable

_38

final String customerSecret = System.getenv("AGORA_CUSTOMER_SECRET");

_38

_38

// App ID

_38

// Set the AGORA_APP_ID variable

_38

final String appid = System.getenv("AGORA_APP_ID");

_38

_38

// Concatenate the customer ID and customer secret and encode them using base64

_38

String plainCredentials = customerKey + ":" + customerSecret;

_38

String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));

_38

// Create the authorization header

_38

String authorizationHeader = "Basic " + base64Credentials

_38

_38

HttpClient client = HttpClient.newHttpClient();

_38

_38

// Create an HTTP request object

_38

HttpRequest request = HttpRequest.newBuilder()

_38

.uri(URI.create("http://api.sd-rtn.com/dev/v1/channel/" + appid))

_38

.GET()

_38

.header("Authorization", authorizationHeader)

_38

.header("Content-Type", "application/json")

_38

.build();

_38

// Send an HTTP request

_38

HttpResponse<String> response = client.send(request,

_38

HttpResponse.BodyHandlers.ofString());

_38

_38

System.out.println(response.body());

_38

// Add the subsequent processing logic for the response content

_38

}

_38

}

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

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.

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