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 use-cases
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 use-case where the number of concurrent channels is not large, directly query the channel list to sync the channel status. In a use-case 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, use the following code to send a simple request to obtain the total number of channels and the number of users in each channel:

Java

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("http://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   }}

Golang

package mainimport (	"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", "http://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 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.