Console RESTful API

1. Authorization

The RESTful API only supports HTTPS, and the user must pass the basic HTTP authentication with the following information:

• User Name: Customer ID
• Password: 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.

You can 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.
Currently, the Vendor Key and Sign Key are renamed to the App ID and App Certificate respectively on the Console, but vendor_key and sign_key are still used in this document.

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 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 banned user receives the corresponding callback as follows:

• Android: onConnectionBanned
• iOS/macOS:ConnectionDidBanned
• Web:onclient-banned
• Windows:onConnectionBanned

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"]
    }

• 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：http://api.agora.io/dev/v1/.

To ensure the availability of this function to all our customers, Agora decides to rate limit on the call frequency of this API. When this frequency limit is exceeded, the HTTP Error Code 429 (Too Many Requests) is triggered. Agora considers this frequency limit adequate for most of our customers in most scenarios. Should you receive this Error Code, Agora recommends adjusting your call frequency. Should this limit fails to meet your need, please contact sales-us@agora.io.

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

About the User Role

At present, the user roles, also called online roles, retrieved by the RESTful API is different from the roles that are specified in the setClientRole method. The online roles are distinguished by the channel profile and the type of the upstream media data. Currently we have the following 5 online roles:

Online Role	Enumeration
Unknown role	0
Communication user	1
Video live broadcaster	2
Live broadcast audience	3
Audio live broadcaster	4

At present, the role of the Audio live broadcaster has yet to be distinguished and will be categorized as the Live broadcast audience.

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 4: Audio live broadcaster

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:

   // If it is a communication channel:
   {
           "success": true,
           "data": {
                   "channel_exist": true,
                   "mode": 1,
                   "total": 1,
                   "users": [<uid>]
           }
   }
  
   // If it is a live-broadcast channel:
   {
           "success": true,
           "data": {
                   "channel_exist": true,
                   "mode": 2
                   "broadcasters": [<uid>],
                   "audience": [<uid>]
                   "auience_total": <count>
           }
   }
  
   // If the channel does not exist:
   {
           "success": true,
           "data": {
                   "channel_exist": false
           }
   }

  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

Get the Project 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.

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

The channel lists retrieved in this method will cache for 1 minute. And if you use this method twice within 1 minute, the result stays the same.

Check if a User is a Co-host (GET)

This method checks if a user is a co-host in a specified channel.

• Method: GET

• Path: BaseUrl/channel/business/hostin/

• 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/business/hostin/<appid>/<uid>/<channelName>

• Response:

   {
       "success": true,
       "data": {
           "isHostIn": false
       }
   }

  Name	Description
  success	Checks the request state: true: Request succeeded false: Request failed
  isHostIn	Checks if the user is hosting: true: User is in the hosting role false: User is not in the hosting role

7. Error Codes

See Error Codes and Warning Codes.