Skip to main content

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 and scenarios

Key featuresDescriptionTypical application scenarios
Manage user privilegesIncludes 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 informationQuery 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.

Authorization

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.

Domain

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.

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.

Video Calling