1. Authentication

Before using the RESTful APIs, ensure that your account has enabled the relevant privilege of a specified project in Agora Console. Agora supports customizing different user roles and privileges. For more information, see Management members.

The RESTful API only supports HTTPS, and the user must pass the Authorization parameter in the Basic HTTP request header for authentication. You need to pass the Customer ID and Customer Cerficate in the code.

Login https://console.agora.io, click the account name on the top right of the Console, and enter the RESTful API page from the drop-down list to get the Customer ID and Customer Certificate.

Unlike the App ID and App Certificate used for Agora SDKs, the Customer ID and Customer Certificate are only used for RESTful API access.

For how to generate the Authorization parameter, see RESTful API authentication.

2. EndPoint

All requests should be sent to BaseUrl: https://api.agora.io/dev/v1.

  • Request: All parameters must be sent in JSON format, with content type: Content-Type: application/json.

  • Response: The response content is in JSON format. The response status is defined as follows:

    • Status 200: Request handle successful.
    • Status 400: The input is in the wrong format.
    • Status 401: Unauthorized (incorrect App ID/Customer Certificate).
    • Status 404: Wrong API invoked.
    • Status 429: Too frequent API calls.
    • Status 500: Internal error of the Agora RESTfulAPI service.

3. Project API

BaseUrl: https://api.agora.io/dev/v1.

The following chart shows how you can use Project APIs.

Fetch all Projects (GET)

  • Method: GET

  • Path: BaseUrl/projects/

  • Parameter: None

  • Response:

     {
         "projects":[
    
                                 {
    
                                     "id": 'xxxx',
                                     "name": 'project1',
                                     "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                                     "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                                     "recording_server": '10.2.2.8:8080',
                                     "status": 1,
                                     "created": 1464165672
    
                                 }
    
                          ]
     }
  • Status:

    • 1: Active
    • 0: Disable

Fetch a Single Project (GET)

  • Method: GET

  • Path: BaseUrl/project/

  • Parameter:

     {
         "id":'xxxx',
         "name":'xxxx'
     }
  • Response:

     {
         "projects":[
    
                          {
    
                                     "id": 'xxxx',
                                     "name": 'project1',
                                     "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                                     "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                                     "recording_server": '10.2.2.8:8080',
                                     "status": 1,
                                     "created": 1464165672
    
                                 }
    
                          ]
     }
  • Status:

    • 1: Active
    • 0: Disable

Create a Project (POST)

  • Method: POST

  • Path: BaseUrl/project/

  • Parameter:

     {
         "name":'projectx',
         "enable_sign_key": true
     }
  • Response

      {
          "project":
                          {
    
                               "id": 'xxxx',
                               "name": 'project1',
                               "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                               "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                               "status": 1,
                               "created": 1464165672
    
                          }
      }

Disable/Enable a Project (POST)

  • Method: POST

  • Path: BaseUrl/project_status/

  • Parameter:

     {
         "id":'xxx',
         "status": 0
     }
  • Response:

    • Success:

           {
               "project":
                               {
      
                                "id": 'xxxx',
                                "name": 'project1',
                                "vendor_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                                "sign_key": '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
                                "status": 0,
                                "created": 1464165672
      
                                }
      
            }
           ```
    • If a specified project does not exist (deleted or no such project):

       status 404
       content:
       {
      
         "error_msg": "project not exist"
      
       }

Delete a Project (DELETE)

  • Method: DELETE

  • Path: BaseUrl/project/

  • Parameter:

     {
         "id":'xxxx'
     }
  • Response:

    • Project deleted:

        {
            "success": true
        }
    • Project not found:

        status 404
      
         {
                "error_msg": "project not exist"
         }

Set a Project’s Recording Server IP (POST)

  • Method: POST

  • Path: BaseUrl/recording_config/

  • Parameter:

     {
         "id":'xxxx',
         "recording_server": '10.12.1.5:8080'
     }
  • If your Recording SDK version is before v1.9.0 (include), please pay attention to the recording_server parameter.
  • If your Recording SDK version is later than v1.11.0 (include), please neglect the recording_server parameter.
  • Response:

    • Success:

        {
            "success": true
        }
    • Project not found or disabled:

      status 404
      
      {
       "error_msg": "project not exist"
      }

Enable a Project’s App Certificate (POST)

  • Method: POST

  • Path: BaseUrl/signkey/

  • Parameter:

     {
         "id": `xxx`,
         "enable": true
     }
  • Response:

    • Success:

        {
      
            "success": true
      
        }
    • Project not found or disabled:

        status 404
        {
      
            "error_msg": "project not exist"
      
        }

Reset a Project’s App Certificate (POST)

  • Method: POST

  • Path: BaseUrl/reset_signkey/

  • Parameter:

     { "id" : "xxx"}   // project id
  • Response:

    • Success:

        {
            "success": true
        }
    • Project not found or disabled:

        status 404
            {
                "error_msg": "project not exist"
            }

If an App Certificate is not enabled for a project, calling this method will enable it.

4. Usage API

BaseUrl: https://api.agora.io/dev/v1.

The following chart shows how you can use Usage APIs.

Fetch Usages (GET)

  • Method: GET

  • Path: BaseUrl/usage/

  • Parameter: (from date & to date pattern: YYYY-MM-DD)

     "from_date"=YYYY-MM-DD&to\_date=YYYY-MM-DD&projects=id1,id2,id3
     "from_date"=2015-01-01&to_date=2015-03-21&projects=id1,id2

    It is optional to specify projects. If it is not specified, the usage is queried on all projects of this account.

  • Response:

    • Success:

        {
            "usages":[
      
                                { "project": 'xxx',
                                                        "daily": [
                                                                    { "date": 20150101, "audio": 20, "sd": 100, "hd": 132, "hdp": 225},
                                                                    { "date": 20150102, "audio": 20, "sd": 100, "hd": 132, "hdp": 225},
                                                            ]
                                                        },
      
                                                        { "project": 'yyy',
                                                            "daily": [....]
                                                        }
      
                            ]
        }
    • Error:

      If some of the specified projects do not exist, they will be omitted and no error will occur.

The audio, sd, hd and hdp parameters in this response are in minutes.

5. Ban Users at the Server

BaseUrl: https://api.agora.io/dev/v1.

The following chart shows how you can use related APIs.

The call frequency of this group of API is no more than ten queries per second.

The banned user receives the corresponding callback as follows:

Create a Rule (POST)

  • Method: POST

  • Path: BaseUrl/kicking-rule/

  • Parameter:

     {
                 "appid":"",   // Mandatory, project App ID
                 "cname":"",   // Optional, channel name. Do not pass cname:""
                 "uid":"",     // Optional, UID which can be obtained by using the SDK API. Do not pass uid:0
                 "ip":"",      // Optional, IP address of the user to be banned. Do not pass ip:0
                 "time": 60    // Optional, banned period in minutes. 1440 minutes maximum, 1 minute minimum. If you set it to over 1440 minutes, it will be processed as 1440 minutes. If you do not set it, the default duration is 1 hour, that is, time:60 
                 "privileges":["join_channel"]   // The default value.
      }
  • Setting the time argument means that the banning rule does not take effect. The server sets all the users in the channel that comform to the rule offline and the users can log in again to rejoin the channel.
  • The ban rule is based on the permutation and combination of the three fields: cname, uid and ip. See the following examples:
    • If you pass the ip parameter, but not cname or uid, then the rule is that this ip cannot login any channel in the App.
    • If you pass the cname parameter, but not uid or ip, then the rule is that no one can login the channel specified by the cname parameter.
    • If you pass the cname and uid parameter, but not ip, then the rule is that the uid cannot login the channel specified by the cname parameter.
  • Response:

     {
         "status": "success",  // Status of the request
         "id": 1953            // The rule ID. If you want to update the rule, then you need the rule ID to specify one
     }

Get the Rule List (GET)

  • Method: GET

  • Path: BaseUrl/kicking-rule/

  • Parameter:

     {
        "appid":""    // Mandatory, project App ID
      }
  • Response:

     {
         "status": "success",                                    // Status of the request
         "rules": [
             {
                 "id": 1953,                                     // The rule ID. If you want to update the rule, then you need the rule ID to specify one
                 "appid": ""                                     // project App ID
                 "uid": 1,                                       // UID which can be obtained by using the SDK API
                 "opid": 1406,                                   // Operating ID which is used to check the operation records for issues tracking
                 "cname": "11",                                  // The channel name
                 "ip": null,                                     // The IP address
                 "ts": "2018-01-09T07:23:06.000Z",               // Time when the rule takes effect
                 "createAt": "2018-01-09T06:23:06.000Z",         // Time when the rule is created
                 "updateAt": "2018-01-09T14:23:06.000Z"          // Time when the rule is updated
             }
         ]
     }

Update the Rule Period (PUT)

  • Mrethod: PUT

  • Path: BaseUrl/kicking-rule/

  • Parameter :

     {
              "appid":"",   // Mandatory, project App ID
              "id":"",      // Mandatory, rule ID with the rule list to be retrieved
              "time":""     // Mandatory, banned period to be updated
     }
  • Response:

     {
         "result": {
             "id": 1953,                         // The rule ID
             "ts": "2018-01-09T08:45:54.545Z"    // Time when the rule expires
         },
         "status": "success"                     // Status of the request
     }

Delete a Rule (DELETE)

  • Method: DELETE

  • Path: BaseUrl/kicking-rule/

  • Parameter:

     {
                    "appid":"",   // Mandatory, project App ID
                    "id":""       // Mandatory, rule ID with the rule list to be retrieved
     }
  • Response:

     {
         "status": "success",  // Status of the request
         "id": 1953            // The rule ID
     }

6. Online Statistics Query API

BaseUrl:https://api.agora.io/dev/v1/.

The following chart shows how you can use Online Statistics Query APIs.

The call frequency of this group of API is no more than twenty queries per second.

Get a User Role in the Channel (GET)

This method checks if a specified user is in a specified channel, and if yes, checks the role of this user in the channel.

  • Method: GET

  • Path: BaseUrl/channel/user/property/

  • Parameters: appid, uid, cname

    Parameter Description
    appid Mandatory, App ID in the Console
    uid Mandatory, user ID which can be obtained by using the SDK
    cname Mandatory, channel name

Example: /channel/user/property/<appid>/<uid>/<channelName>

  • Response:

     {
         "success": true,
         "data": {
             "join": 1549073054,
             "in_channel": true,
             "role": 2
         }
     }
    Parameter Description
    join

    The timestamp when the user joins the channel

    success

    Checks the request state

    • true: Request succeeded
    • false: Request failed
    in_channel

    Checks if the user is in the channel

    • true: The user is in the channel
    • false: The user is not in the channel
    role

    Checks the role of the user in the channel

    • 0: Unknown role
    • 1: Communication user
    • 2: Video live broadcaster
    • 3: Live broadcast audience

Get the User Role List in a Channel (GET)

This method checks the user role list in a specified channel.

  • Method: GET

  • Path: BaseUrl/channel/user/

  • Parameters: appid, cname

    Parameter Description
    appid Mandatory, App ID in the Console
    cname Mandatory, channel name

Example: /channel/user/<appid>/<channelName>

  • Response: the responses of difference channel profiles differ:

     // If it is a communication channel:
     {
             "success": true,
             "data": {
                     "channel_exist": true,
                     "mode": 1,
                     "total": 1,
                     "users": [<uid>]
             }
     }
    Parameter Description
    success

    Checks the request state:

    • true: Request succeeded
    • false: Request failed
    channel_exist

    Checks if the channel exits:

    • true: Channel exists
    • false: Channel does not exist
    mode

    Checks the channel mode:

    • 1: The communication mode
    • 2: The live broadcast mode
    total Total number of the users in the channel
    users UIDs of all users in the channel

    // If it is a live broadcast channel.
    {
         "success": true,
         "data": {
                 "channel_exist": true,
                 "mode": 2,
                 "broadcaster": [<uid>],
                 "audience": [<uid>],
                 "audience_total": <count>
         }
    }
    Parameter Description
    success

    Checks the request state:

    • true: Request succeeded
    • false: Request failed
    channel_exist

    Checks if the channel exits:

    • true: Channel exists
    • false: Channel does not exist
    mode

    Checks the channel mode:

    • 1: The communication mode
    • 2: The live broadcast mode
    broadcaster The ID list of all the broadcasters in the channel
    audience The ID list of the first 10000 auience in the channel
    audience_total The total number of auience in the channel

Get the Channel List (GET)

This method gets the channel list of a specified vendor.

  • Method: GET

  • Path: BaseUrl/channel/appid/

  • Parameters: ?page_no=0&page_size=100 (Optional)

    Parameter Name
    page_no Optional. The starting page; the default value is 0.
    page_size Optional. The number of items in a page; the default value is 100 and the greatest value is 500.

Example: /channel/<appid>
Example with parameters: /channel/<appid>page_no=0&page_size=100

  • Response:

      {
               "success": true,
               "data": {
                   "channels": [
                       {
                           "channel_name": "lkj144",
                           "user_count": 3
                       }
                   ],
                   "total_size": 3
           }
    
     }
    Parameters Description
    success

    Checks the request state:

    • true: Request succeeded
    • false: Request failed
    channel_name Name of the specified channel
    user_count Total number of users the channel
    total_size Total number of the channel

7. Error Codes

See Error Codes and Warning Codes.