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 in this document 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, p2p: 20, sd: 100, hd: 132, hdp: 225},
                              { date: 20150102, p2p: 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.