With the Agora Media Broadcast RESTful API, you can configure and manage the streaming service at your server by sending HTTP requests to Agora servers.
This page is a basic introduction to the Media Broadcast RESTful API.
The Media Broadcast RESTful API provides the following functions:
There are two types of domain names: Stream-pushing domain names and stream-playing domain names. They mainly affect regional access and stream scheduling. The same live stream can be pushed or played through multiple different domain names.
Entry points are used to group live streams. Once you configure a function such as recording, transcoding, or snapshot capturing for an entry point, that configuration applies to all live streams under this entry point.
You can record the content of a live stream into MP4 and HLS files and upload these files to a third-party cloud storage service.
You can ban or unban a live stream and query stream information and statistics.
Standard recording supports creating clips and snapshots out of a recording file.
Follow these steps to call the Media Broadcast RESTful API:
The Media Broadcast RESTful API uses HTTP HMAC (Hash-based Message Authentication Code) authentication.
When you send an HTTP request, you need to generate a signature using the HMAC-SHA256 algorithm and pass this signature and its related information to the authorization
field.
You need the following Agora account information to generate the authentication field:
To show you how to generate the value of the authorization
field, the following Python code (Python 3.7+) takes the API that lists domain names as an example :
import hmac
import base64
import datetime
from hashlib import sha256
# The App ID of your Agora project
appid = ''
# Get Customer ID in the RESTful API of the Agora Console
customer_username = ''
# Get Customer Secret in the RESTful API of the Agora Console
customer_secret = ''
# Request body
data = ""
# Request host
host = "api.agora.io"
# Request method and endpoint
req_metd = 'GET'
path = f'/v1/projects/{appid}/fls/domains'
body_sha256 = sha256(data.encode('utf-8')).digest()
body_sha256_base64 = base64.b64encode(body_sha256)
date = datetime.datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S GMT')
request_line = "{} {} {}".format(req_metd, path, "HTTP/1.1")
digest = "SHA-256={}".format(body_sha256_base64.decode("utf-8"))
signing_string = "host: {}\ndate: {}\n{}\ndigest: {}".format(host, date, request_line, digest)
signature = base64.b64encode(
hmac.new(customer_secret.encode("utf-8"), signing_string.encode("utf-8"), sha256).digest())
authorization = 'hmac username="{}", algorithm="hmac-sha256", headers="host date request-line digest", signature="{}"'.format(
customer_username, signature.decode("utf-8"))
All requests are sent to the following host: api.agora.io
.
To ensure communication security, the Media Broadcast RESTful API only supports the HTTPS protocol.
All request URLs and request body content is case-sensitive.
The call frequency limit of the Media Broadcast RESTful API is 50 times per second. If the call frequency exceeds the limit, see How can I avoid being frequency limited when calling Agora Server RESTful APIs?.
This section provides complete code samples for calling the Media Broadcast RESTful API.
import hmac
import base64
import datetime
import requests
import json
from hashlib import sha256
# username
customer_username = "hmac_user_name"
# secret
customer_secret = "hmac_user_secret"
# appid
appid = "your_appid"
# streamName
stream_name = "stream_name"
# content
customer_data = json.dumps({"resumeTime":"2023-11-29T19:00:00+08:00"})
body_sha256 = sha256(customer_data.encode('utf-8')).digest()
body_sha256_base64 = base64.b64encode(body_sha256)
host = "api.agora.io"
path = "/v1/projects/%s/fls/entry_points/live/admin/banned_streams/%s" % (appid, stream_name)
date = datetime.datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S GMT')
request_line = "{} {} {}".format("PATCH", path, "HTTP/1.1")
digest = "SHA-256={}".format(body_sha256_base64.decode("utf-8"))
signing_string = "host: {}\ndate: {}\n{}\ndigest: {}".format(host, date, request_line, digest)
signature = base64.b64encode(hmac.new(customer_secret.encode("utf-8"), signing_string.encode("utf-8"), sha256).digest())
authorization = 'hmac username="{}", algorithm="hmac-sha256", headers="host date request-line digest", signature="{}"'.format(customer_username, signature.decode("utf-8"))
print (authorization)
headers = {
"host": host,
"date": date,
"digest": digest,
"authorization": authorization,
}
print(signing_string)
response = requests.patch("https://{}{}".format(host, path), headers=headers, data=customer_data)
print(response.status_code, response.content.decode())
print(response.headers)
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.text.SimpleDateFormat;
import java.util.*;
public class GatewayKey {
public static void main(String[] args) throws NoSuchAlgorithmException, IOException, InvalidKeyException {
String customerUsername = "hmac_user_name";
String customerSecret = "hmac_user_secret";
String customerData = "";
String appid = "your_appid";
String streamName = "stream_name";
String requestMethod = "DELETE";
MessageDigest messageDigest;
messageDigest = MessageDigest.getInstance("SHA-256");
messageDigest.update(customerData.getBytes("UTF-8"));
String base64encodedString = Base64.getEncoder().encodeToString(messageDigest.digest());
String digest = "SHA-256=" + base64encodedString;
String host = "api.agora.io";
String path = String.format("/v1/projects/%s/fls/entry_points/live/admin/banned_streams/%s", appid, streamName);
String requestLine = requestMethod + " " + path + " " + "HTTP/1.1";
final Date currentTime = new Date();
final SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z", Locale.ENGLISH);
sdf.setTimeZone(TimeZone.getTimeZone("GMT"));
String date = sdf.format(currentTime);
String signingString = String.format("host: %s\ndate: %s\n%s\ndigest: %s", host, date, requestLine, digest);
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(customerSecret.getBytes("UTF-8"), "HmacSHA256");
sha256_HMAC.init(secret_key);
String signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(signingString.getBytes("UTF-8")));
String authorization = String.format("hmac username=\"%s\", algorithm=\"hmac-sha256\", headers=\"host date request-line digest\", signature=\"%s\"",
customerUsername, signature);
System.out.println(authorization);
System.out.println(signingString);
URL url = new URL("https://" + host + path);
HttpURLConnection http = (HttpURLConnection)url.openConnection();
http.setRequestMethod("DELETE");
http.setDoOutput(true);
http.setRequestProperty("host", host);
http.setRequestProperty("date", date);
http.setRequestProperty("digest", digest);
http.setRequestProperty("authorization", authorization);
OutputStream stream = http.getOutputStream();
stream.write(customerData.getBytes("UTF-8"));
System.out.println(http.getResponseCode() + " " + http.getResponseMessage());
BufferedReader br = null;
if (http.getResponseCode() == 200) {
br = new BufferedReader(new InputStreamReader(http.getInputStream()));
String strCurrentLine;
while ((strCurrentLine = br.readLine()) != null) {
System.out.println(strCurrentLine);
}
} else {
br = new BufferedReader(new InputStreamReader(http.getErrorStream()));
String strCurrentLine;
while ((strCurrentLine = br.readLine()) != null) {
System.out.println(strCurrentLine);
}
}
http.disconnect();
}
}
var crypto = require("crypto");
var request = require("request");
var customer_username = "{your_hmac_key}";
var customer_secret = "{your_hmac_secret}";
var host = "api.agora.io";
var path = "/v1/projects/{appid}/fls/entry_points/live/admin/banned_streams/{streamName}";
var method = "PATCH";
var content = {};
content.resumeTime = "2023-11-29T19:00:00+08:00";
var contentString = JSON.stringify(content);
gmt_date = new Date().toGMTString();
digest = "SHA-256=" + Buffer.from(crypto.createHash("sha256").update(contentString).digest()).toString("base64");
request_line = method + " " + path + " " + "HTTP/1.1";
signing_string = "host: " + host;
signing_string = signing_string + "\ndate: " + gmt_date;
signing_string = signing_string + "\n" + request_line;
signing_string = signing_string + "\ndigest: " + digest;
signature = crypto.createHmac("sha256", customer_secret).update(signing_string).digest();
signature = Buffer.from(signature).toString("base64");
authorization = 'hmac username="' + customer_username + '", ';
authorization = authorization + 'algorithm="hmac-sha256", headers="host date request-line digest", signature="';
authorization = authorization + signature + '"';
request.patch(
{
url: "https://" + host + path,
headers: {"content-type": "application/json", date: gmt_date, digest: digest, authorization: authorization},
body: contentString,
},
function (err, res, body) {
console.log("err:", err);
console.log("status:", res.statusCode);
console.log("body:", body);
},
);
<?php
# Your Customer ID retrieved from Agora Console
$customer_username = "{your username}";
# Your Customer Secret retrieved from Agora Console
$customer_secret = "{your secret}";
# Your App ID retrieved from Agora Console
$appid = "{your appid}";
$request_method = "PATCH";
# Requesy body
$data = "";
$host = "api.agora.io";
$entry_point = "live";
$path = sprintf("/v1/projects/%s/fls/entry_points/%s/reports/online_streams", $appid, $entry_point);
$date = gmDate("D, d M Y H:i:s ", time()) . "GMT";
$request_lint = sprintf("%s %s %s", $request_method, $path, "HTTP/1.1");
$data = trim($data);
$digest = 'SHA-256=' . base64_encode(pack("H*", hash("sha256", $data)));
$signing_string = sprintf("host: %s\ndate: %s\n%s\ndigest: %s", $host,$date,$request_lint,$digest);
$signature = base64_encode(pack('H*', hash_hmac('sha256', $signing_string, $customer_secret)));
$authorization = sprintf('hmac username="%s", algorithm="hmac-sha256", headers="host date request-line digest", signature="%s"', $customer_username, $signature);
$header = [
"host: $host",
"date: $date",
"digest: $digest",
"authorization: $authorization",
];
var_dump($header);
var_dump(getCurl("https://$host$path", $header, $request_method, $data));
function getCurl($url, $headerArray, $method, $data){
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch,CURLOPT_HTTPHEADER,$headerArray);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
$output = curl_exec($ch);
curl_close($ch);
$output = json_decode($output,true);
return $output;
}
var customer_username = "hmac_user_name"
var customer_secret = "hmac_user_secret"
gmt_date = new Date().toGMTString()
digest = "SHA-256=" + CryptoJS.enc.Base64.stringify(CryptoJS.SHA256(pm.request.body.raw))
request_line = pm.request.method + " " + pm.request.url.getPath() + " " + "HTTP/1.1"
signing_string = "host: " + pm.request.url.getHost()
signing_string = signing_string + "\ndate: " + gmt_date
signing_string = signing_string + "\n" + request_line
signing_string = signing_string + "\ndigest: " + digest
signature = CryptoJS.HmacSHA256(signing_string, customer_secret)
signature = CryptoJS.enc.Base64.stringify(signature)
authorization = 'hmac username="' + customer_username + '", '
authorization = authorization + 'algorithm="hmac-sha256", headers="host date request-line digest", signature="'
authorization = authorization + signature + '"'
pm.request.headers.add({key: 'date', value: gmt_date})
pm.request.headers.add({key: 'digest', value: digest})
pm.request.headers.add({key: 'authorization', value: authorization})