Dashboard RESTful API

Dashboard RESTful API

Authentication

The RESTful API only supports HTTPS, and the HTTP access must be authenticated by providing the following information:

  • User Name: Customer ID
  • Password: Customer Certificate

The Customer ID and Customer Certificate are only used for RESTful API access, which are different from the App ID and App Certificate used for Agora SDKs.

Note

Sign into https://dashboard.agora.io, click the account name on the top-right of the dashboard, and enter the RESTful API page from the drop-down menu to get the Customer ID and Customer Certificate.

The Vendor Key and Sign Key are renamed to the App ID and App Certificate on the dashboard, but vendor_key and sign_key are still referred to in this document.

EndPoint

Send all requests to https://api.agora.io/.

Request

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: The request was handled successfully
  • Status 401: Unauthorized (Incorrect App ID/Customer Certificate combination)
  • Status 400: The input is in the wrong format
  • Status 404: The wrong API was invoked
  • Status 500: Internal error of the Agora RestfulAPI service

API Reference

Project API

Fetch All Projects

  • Method:

    Get

  • Path:

    /projects/

  • Parameters:

    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/

  • Parameters:

{
  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 a Project

  • Method:

    Post

  • Path:

    /project/

  • Parameters:

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

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

          }
}

Disable/Enable a Project

  • Method:

    Post

  • Path:

    /project_status/

  • Parameters:

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

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

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

Delete a Project

  • Method:

    Delete

  • Path:

    /project/

  • Parameters:

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

 {
    error_msg: "project not exist"
 }

Set the Recording Server IP

  • Method:

    Post

  • Path:

    /recording_config/

  • Parameters:

{
  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 the Project App Certificate

  • Method:

    Post

  • Path:

    /signkey/

  • Parameters:

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

  success: true

}
  • Project not found or disabled
status 404
{

  error_msg: "project not exist"

}

Reset the Project App Certificate

  • Method:

    Post

  • Path:

    /rest_signkey/

  • Parameters:

{ 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/

  • Parameters: (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 and no error will occur.

Ban Users at the Server Side

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

Create Rule (post)

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

Get Rule List (get)

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

Update Rule Period (put)

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

Delete Rule (delete)

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