API overview

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.

Media Broadcast is currently in public beta. To enable this service, contact sales@agora.io.

Functions

The Media Broadcast RESTful API provides the following functions:

Domain name and entry-point management

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.

Stream recording

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.

Stream processing

Snapshot and content moderation: You can get snapshots of a live stream at regular intervals and upload them to a third-party cloud storage service or a content moderation service.
Transcoding: Transcoding a live stream modifies the audio and video encoder configuration, using either the preset templates or a custom configuration.
Watermark: Adding a watermark to a live stream takes effect on both the original stream and the transcoded stream.

Stream management

You can ban or unban a live stream and query stream information and statistics.

Stream authentication

Timestamp authentication: Set an authentication key for a stream-pushing or stream-playing domain name.
Origin authentication: Send authentication requests to your origin server synchronously or asynchronously. You can also cache the authentication results.

Recording processing

Standard recording supports creating clips and snapshots out of a recording file.

Implementation

Follow these steps to call the Media Broadcast RESTful API:

Add the stream-pushing domain name and the stream-playing domain name.
(Optional) Add an entry point. This step is optional. Agora provides a default entry point that you can use directly.
Call the API to configure streaming functions as needed.

Request structure

Authentication

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:

The App ID of your Agora project. See Get the App ID.
A Customer ID/Customer Secret pair. See Generate a Customer ID and Customer Secret.

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"))

Request: Refer to the example for each API endpoint.
Response: The format of responses is JSON.

All request URLs and request body content is case-sensitive.

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)

Java

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();
    }
}

Node.js

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

<?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;
}

Postman Pre-request Script

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})

Agora Developer Center