Dashboard RESTful API

Dashboard RESTful API

Authentication

RESTful API only supports HTTPS, and the user must pass the basic HTTP authentication by presenting 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.

Note

You can log onto https://dashboard.agora.io, click the account name on the right top of the dashboard, and enter the Restful API page from the drop-down list to fetch the Customer ID and Customer Certificate.

Currently Vendor Key and Sign Key are renamed to App ID and App Certificate on the Dashboard, but the codes included on this page still use vendor_key and sign_key.

EndPoint

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

Request

Parameters must be sent in JSON, with content type: Content-Type: application/json

Response

Response content is JSON format. Response status defined as below:

  • Status 200: request handle successfully
  • Status 401: unauthorized (incorrect App ID/ Customer Certificate pair)
  • Status 400: input is in wrong format
  • Status 404: wrong API invoking
  • Status 500: internal error of Agora RestfulAPI service

API Reference

Project API

Fetch All Projects

  • Method

    Get

  • Path

    /projects/

  • Params

    None

  • Response:

{
  projects:[

              {

                id: 'xxxx',
                name: 'project1',
                vendor_key: '4855898a22ae4102a29b81ba76f2eae2',
                sign_key: '4855898a22ae4102a29b81ba76f2eae2',
                recording_server: '10.2.2.8:8080',
                status: 1,
                created: 1464165672

              }

           ]
}

Status:

  • 1: active
  • 0: disable

Fetch a Single Project

  • Method

    Get

  • Path

    /project/

  • Params

{
  id:'xxxx',
  name:'xxxx'
}
  • Response:
{
  projects:[

           {

                id: 'xxxx',
                name: 'project1',
                vendor_key: '4855898a22ae4102a29b81ba76f2eae2',
                sign_key: '4855898a22ae4102a29b81ba76f2eae2',
                recording_server: '10.2.2.8:8080',
                status: 1,
                created: 1464165672

              }

           ]
}

Status:

  • 1: active
  • 0: disable

Create Project

  • Method

    Post

  • Path

    /project/

  • Params

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

             id: 'xxxx',
             name: 'project1',
             vendor_key: '4855898a22ae4102a29b81ba76f2eae2',
             sign_key: '4855898a22ae4102a29b81ba76f2eae2',
             status: 1,
             created: 1464165672

          }
}

Disable/Enable Project

  • Method

    Post

  • Path

    /project_status/

  • Params

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

    • Success:
    {
      project:
              {
    
               id: 'xxxx',
               name: 'project1',
               vendor_key: '4855898a22ae4102a29b81ba76f2eae2',
               sign_key: '4855898a22ae4102a29b81ba76f2eae2',
               status: 0,
               created: 1464165672
    
               }
    
     }
    
    • If specified project is absent (deleted or no such project):

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

Delete Project

  • Method

    Delete

  • Path

    /project/

  • Params

{
  id:'xxxx'
}
  • Response
  • project deleted
{
  success: true
}
  • project not found
status 404

 {
    error_msg: "project not exist"
 }

Set Project Recording Server IP

  • Method

    Post

  • Path

    /recording_config/

  • Params

{
  id:'xxxx',
  recording_server: '10.12.1.5:8080'
}
  • Response
  • Success
{
  success: true
}
  • project not found or disabled

    status 404
    
     {
       error_msg: "project not exist"
     }
    

Disable/Enable Project App Certificate

  • Method

    Post

  • Path

    /signkey/

  • Params

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

  success: true

}
  • project not found or disabled
status 404
{

  error_msg: "project not exist"

}

Reset Project App Certificate

  • Method

    Post

  • Path

    /rest_signkey/

  • Params

{ id : “xxx”} // project id
  • Response
  • Success
{
  success: true
}
  • project not found or disabled
status 404
  {
    error_msg: "project not exist"
  }

Note

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

USAGE API

Fetch Usages

  • Method

    Get

  • Path

    /usage/

  • Params (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 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. No error will occur.

Kick out Users at Server Side

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

Create Rule (post)

  • type: post
  • url: /kicking-rule
  • parameter:
{
        appid:"",   // Mandatory, the project App ID
        cname:"",   // Optional, the channel name
        uid:"",     // Optional, uid which can get by using the SDK API
        ip:"",      // Optional, the IP address of the user to be bannded
        time: 60    // Optional, the banned period in minutes. 1440 minutes in maximum,and 1 minute in miminum. If you set it over 1440 minutes, it will be processed as 1440 minutes
 }

Get Rule List (get)

  • type: get
  • url: /kicking-rule
  • parameter:
{
   appid:""    // Mandatory, the project App ID
 }

Update Rule Period (put)

  • type: put
  • url: /kicking-rule
  • parameter :
{
         appid:"",   // Mandatory, the project App ID
         id:"",      // Mandatory, the rule ID with rule list to be retrieved
         time:""     // Mandatory, the banned period to be updated
}

Delete Rule (delete)

  • type: delete
  • url: /kicking-rule
  • parameter:
{
               appid:"",   // Mandatory, the project App ID
               id:""       // Mandatory, the rule ID with rule list to be retrieved
}

Live Broadcast Hostin API

BaseUrl:http://api.agora.io/dev/v1/broadcastapp/ (Test environment)

Background interface (parameter reference): https://agoraio.atlassian.net/wiki/spaces/EN/pages/225083744/Online+Stats+RESTful+API+Document+Draft

Check user role in the channel (get)

  • type: get

  • url: /broadcastapp/user/property

  • parameters:

    {
                appid:"",   // Mandatory, the project App ID in the dashboard
                uid:""      // Mandatory, uid which you can get by using the SDK API
                cname:"",   // Mandatory, the channel name
    
    }
    

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

  • response:

    {
    "success": true,              // Request state
    "data": {
        "in_channel": false,      // Whether in the channel or not
        "role": 2                 // Eum: 0: Unknown; 1: Communication user; 2: Live broadcast host; 3: Audience in host mode
         }
    }
    

Check user role list in a specified channel (get)

  • type: get

  • /broadcastapp/channel/user

  • parameters:

    {
                appid:"",   // Mandatory, the App ID in the dashboard
                cname:"",   // Mandatory, the channel name
    
    }
    

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

  • response:

    // Live broadcast channel
    {
         "success": true,                  // Request state
         "data": {
             "channel_exist": true,        // Whether the channel exists or not
             "mode": 2,                    // 1: Communication user; 2: Live broadcast host
             "broadcasters": [<uid>],      // Number of hosts; each list returns 10,000 users at most. Paging not supported.
             "audience": [<uid>],          // Number of audience; each list returns 10,000 users at most. Paging not supported.
             "audience_total": <count>     // Total number of audience
         }
     }
    
    // Communication channel
    {
         "success": true,                // Request state
         "data": {
             "channel_exist": true,      // Whether the channel exists or not
             "mode": 1,                  // 1: Communication user; 2: Live broadcast host
             "total": 1,                 // Number of user
             "users": [
                 <uid>
             ]                           //  Each list returns 10,000 users at most; Paging not supported.
          }
     }
    
    // No channel
    {
        "success": true,                // Request state
        "data": {
            "channel_exist": false
        }
    }
    

Check the channel list of a specified vendor (get)

  • type: get

  • url: /broadcastapp/channel

  • parameters:

    {
              appid:"",                             // Mandatory, the App ID in the dashboard
              ?offset=0&limit=20                    // Optional
              offset                                // The starting site; default value 0
              limit                                 // Page of each item; default value 100
    
    }
    

Example: /broadcastapp/channel/<appid>

Example with parameters: /broadcastapp/channel/<appid>/?offset=0&limit=20

  • response:

     {
              "success": true,                                // Request state
              "data": {
                  "channels": [
                      {
                          "channel_name": "lkj144",           // Channel name
                          "uer_count": 3                      // User name
                      }
                  ],
                  "total_size": 3                             // Total number of the channels
          }
    
    }
    

Check if a specified user is a delegated host in a specified channel (get)

  • type: get

  • url: /broadcastapp/business/hostin

  • parameters:

    {
                appid:"",   // Mandatory, the App ID in the dashboard
                uid:""      // Mandatory, uid which you can get by using the SDK API
                cname:"",   // Mandatory, the channel name
    
    }
    

Example: /broadcastapp/business/hostin/<appid>/<uid>/<channelName>

  • response:

    {
        "success": true,                                 // Request state
        "data": {
            "isHostIn": false                            // Check if the channel exists
        }
    }
    

Note

Possible error: Parameters of the abnormal