Agora Console REST API

When you need to create and manage Agora projects or check usage, besides using the graphic user interface at Agora Console, you can also call the Agora Console RESTful API.

This page provides detailed help for the Agora Console RESTful APIs.

Basic information

This section provides basic information about the Agora Console RESTful APIs.

Domain

All requests are sent to the host: api.agora.io.

Data format

The Content-Type field in all HTTP request headers is application/json. All requests and responses are in JSON format. All request URLs and request bodies are case-sensitive.

The Agora Console RESTful APIs only support HTTPS. Before sending HTTP requests, you must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and pass the credential to the Authorization field in the HTTP request header.

Call frequency limit

For each Agora account (not each App ID), the call frequency of each API on this page is no more than 10 queries per second.

Create a project

Creates an Agora project.

Prototype

Method: POST
Endpoint: https://api.agora.io/dev/v1/project

Request parameters

Request body parameters

Pass in the following parameters in the request body:

Parameter	Type	Description
`name`	String	(Required) The project name, which is between 1 to 255 characters in length.
`enable_sign_key`	Boolean	(Required) Whether to enable the primary app certificate: true: Enable the primary app certificate. false: (Default) Do not enable the primary app certificate. Note: After creating a project, you can send a request to `https://api.agora.io/dev/v1/signkey` to enable or disable the primary app certificate, or send a request to `https://api.agora.io/dev/v1/reset_signkey` to reset the primary app certificate.

Request example

Request body

{
  "name": "project1",
  "enable_sign_key": true
}

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`project`	Object	The information on the project, including the following fields: `id`: String. The project ID `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary app certificate of the project. `recording_server`: String. The IP address of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

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

Get a specified project

Gets the information on a specified project.

Prototype

Method: GET
Endpoint: https://api.agora.io/dev/v1/project

Request Parameters

Query parameters

Pass in the following query parameters in the request URL:

Parameter	Type	Description
`id`	String	(Required) The project ID, which can be obtained by calling the Gets all projects API.
`name`	String	(Required) The project name.

Request example

Request URL

https://api.agora.io/dev/v1/project?id=7sdnf3xRH&name=project1

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`projects`	Array	The information on the projects. This Array consists of multiple Objects. Each Object shows the information on one project and includes the following fields: `id`: String. The project ID. `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary App Certificate of the project. `recording_server`: String. The IP of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

{
    "projects": [
        {
            "id": "xxxx",
            "name": "project1",
            "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "recording_server": null,
            "status": 1,
            "created": 1464165672
        }
    ]
}

Get all projects

Gets the information on all your Agora projects.

Prototype

Method: GET
Endpoint: https://api.agora.io/dev/v1/projects

Request example

Request URL

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

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`projects`	Array	The information on the projects. This Array consists of multiple Objects. Each Object shows the information on one project and includes the following fields: `id`: String. The project ID. `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary App Certificate of the project. `recording_server`: String. The IP of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

{
    "projects": [
        {
            "id": "xxxx",
            "name": "project1",
            "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "recording_server": null,
            "status": 1,
            "created": 1464165672
        },
        {
            "id": "xxxx",
            "name": "project1",
            "sign_key": "2c01da6d6f6741df88ec47005f08572b",
            "vendor_key": "eb00cd2b222a4eeaa24fc6046d90b227",
            "recording_server": null,
            "status": 1,
            "created": 1637153755
        }
    ]
}

Disable or enable a project

Disables or enables a specified Agora project.

Prototype

Method: POST
Endpoint: https://api.agora.io/dev/v1/project_status

Request parameters

Request body parameters

Pass in the following parameters in the request body:

Parameter	Type	Description
`id`	String	(Required) The project ID, which can be obtained by calling the Gets all projects API.
`status`	Number	(Required) Whether to enable or disable the project: `0`: Disable the project. `1`: Enable the project.

Request example

Request body

{
  "id": "xxxx",
  "status": 0
}

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`project`	Object	The information on the project, including the following fields: `id`: String. The project ID. `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary app certificate of the project. `recording_server`: String. The IP address of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

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

Set the IP address of the recording server

Sets the IP of the recording server for a specified project.

Prototype

Method: POST
Endpoint: https://api.agora.io/dev/v1/recording_config

Request parameters

Request body parameters

Pass in the following parameters in the request body:

Parameter	Type	Description
`id`	String	(Required) The project ID, which can be obtained by calling the Gets all projects API.
`recording_server`	String	(Required) The IP address of the recording server. This field takes effect only when you use v1.9.0 or earlier versions of Agora On-premise Recording SDK.

Request example

Request body

{
  "id": "xxxx",
  "recording_server": "10.12.1.5:8080"
}

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`project`	Object	The information on the project, including the following fields: `id`: String. The project ID. `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary app certificate of the project. `recording_server`: String. The IP address of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

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

Enable or disable the primary app certificate

Enables or disables the primary app certificate for a specified project.

Prototype

Method: POST
Endpoint: https://api.agora.io/dev/v1/signkey

Request parameters

Request body parameters

The following parameters are required in the request body:

Parameter	Type	Description
`id`	String	(Required) The project ID, which can be obtained by calling the Gets all projects API.
`enable`	Boolean a	(Required) Whether to enable or disable the primary app certificate for the project: true: (Default) Enable the primary app certificate. false: Do not enable the primary app certificate.

Request example

Request body

{
  "id": "xxxx",
  "enable": true
}

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`project`	Object	The information on the project, including the following fields: `id`: String. The project ID. `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary app certificate of the project. `recording_server`: String. The IP address of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

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

Reset the primary app certificate

Resets the primary app certificate for a specified project.

Prototype

Method: POST
Endpoint: https://api.agora.io/dev/v1/reset_signkey

Request parameter

Request body parameter

Pass in the following parameter in the request body:

Parameter	Type	Description
`id`	String	(Required) The project ID, which can be obtained by calling the Gets all projects API.

Request example

Request body

{
  "id": "xxxx"
}

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 201, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 201, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`project`	Object	The information on the project, including the following fields: `id`: String. The project ID. `name`: String. The project name. `vendor_key`: String. The App ID of the project. `sign_key`: String. The primary app certificate of the project. `recording_server`: String. The IP address of the recording server. Pay attention to this field if you use v1.9.0 and earlier versions of the Agora On-premise Recording SDK. Ignore this field if you use v1.11.0 and later versions of the Agora On-premise Recording SDK. `status`: Number. The status of the project: `1`: The project is enabled. `0`: The project is disabled. `created`: Number. The Unix timestamp (in seconds) of when the project is created.

Response example

The following is a response example for a successful request:

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

Get project usage

Gets the usage data of a specified project.

Prototype

Method: GET
Endpoint: https://api.agora.io/dev/v3/usage

Request parameters

Query parameters

Pass the following query parameters in the request path:

Parameter	Type	Description
`project_id`	String	(Required) The project ID, which can be obtained by calling the Gets all projects API.
`from_date`	String	(Required) The start date of the query, UTC time. For example, 2020-01-01.
`to_date`	String	(Required) The end date of the query, UTC time. For example, 2020-01-31.
`business`	String a	(Required) The business type. You can choose one of the following values: `default`: Audio and video. The usage on Miniapp is not included. `transcodeDuration`: Transcoding. `recording`: On-premise recording. `cloudRecording`: Cloud recording. `miniapp`: Miniapp.

Request example

Request path

https://api.agora.io/dev/v3/usage?project_id=rxxxxxxj5u&from_date=2021-10-12&to_date=2021-12-14&business=default

Response parameters

For details about possible response status codes, see the Response status codes table.

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 200, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
`meta`	Object	Metadata, which describes the meaning of `durationAudioAll`, `durationVideo1080P`, `durationVideo2K`, `durationVideo4K`, `durationVideoHd` and `durationVideoHdp` in the `usage` parameter. `durationAudioAll`: Object. Total audio duration. `cn`: String. `durationAudioAll` in Chinese, that is, "总音频时长". `en`: String . `durationAudioAll` in English, that is, "Total Audio Duration". `unit`: String. The unit of audio duration, in seconds. `durationVideo1080P`: Object. Total Full HD video duration. `cn`: String. `durationVideo1080P` in Chinese, that is, "1080P视频时长（含录制）“. `en`: String . `durationVideo1080P` in English, that is, "Full HD Video Duration (including Recording)". `unit`: String . The unit of Full HD video duration, in seconds. `durationVideo2K`: Object. Total duration of 2K video. `cn`: String. `durationVideo2K` in Chinese, that is, "2K视频时长（含录制）". `en`: String. `durationVideo2K` in English, that is, "2K Video Duration（including Recording)". `unit`: String . The unit of 2K video duration, in seconds. `durationVideo4K`: Object. Total duration of 2K+ video. `cn`: String.`durationVideo4K` in Chinese, that is, "2K+ 视频时长（含录制）". `en`: String. `durationVideo4K` in English, that is, "2K+ Video Duration（including Recording)". `unit`: String. The unit of 2K+ video duration, in seconds. `durationVideoHd`: Total duration of HD video. `cn`: String. `durationVideoHd` in Chinese, that is, "HD视频时长（含录制）". `en`: String. `durationVideoHd` in English, that is, "HD Video Duration (including On premise Recording)". `unit`: String. The unit of HD video duration, in seconds. `durationVideoHdp`: Total duration of Hdp video. `cn`: String. `durationVideoHdp` in Chinese, that is, "HDP视频时长（含录制）". `en`: String. `durationVideoHdp` in English, that is, "HDP Video Duration（including Recording)". `unit`: String. The unit of HDP video duration, in seconds.
`usages`	Array	Usage of the specified project. This array consists of multiple objects. Each object shows the usage of a specific day and includes the following fields: `date`: Number. The query date, using UTC time and Unix timestamp. `usage`: Object. The usage of the query date. `durationAudioAll`: Number. Total duration of the audio, in seconds. `durationVideo1080P`: Number. Total duration of Full HD video, in seconds. `durationVideo2K`: Number. Total duration of 2K video, in seconds. `durationVideo4K`: Number. Total duration of 2K+ video, in seconds. `durationVideoHd`: Number. Total duration of HD video, in seconds. `durationVideoHdp`: Number. Total duration of HDP video, in seconds.

Response example

The following is a response example for a successful request:

{
    "meta": {
        "durationAudioAll": {
            "cn": "总音频时长",
            "en": "Total Audio Duration",
            "unit": "second"
        },
        "durationVideo1080P": {
            "cn": "1080P视频时长（含录制）",
            "en": "Full HD Video Duration（including Recording)",
            "unit": "second"
        },
        "durationVideo2K": {
            "cn": "2K视频时长（含录制）",
            "en": "2K Video Duration（including Recording)",
            "unit": "second"
        },
        "durationVideo4K": {
            "cn": "4K视频时长（含录制）",
            "en": "4K Video Duration（including Recording)",
            "unit": "second"
        },
        "durationVideoHd": {
            "cn": "HD视频时长（含录制）",
            "en": "HD Video Duration（including Recording）",
            "unit": "second"
        },
        "durationVideoHdp": {
            "cn": "HDP视频时长（含录制）",
            "en": "HDP Video Duration（including Recording)",
            "unit": "second"
        }
    },
    "usages": [
        {
            "date": "2021-10-12T00:00:00.000Z",
            "usage": {
                "durationAudioAll": 0,
                "durationVideo1080P": 0,
                "durationVideo2K": 0,
                "durationVideo4K": 0,
                "durationVideoHd": 0,
                "durationVideoHdp": 0
            }
        },
        {
            "date": "2021-10-13T00:00:00.000Z",
            "usage": {
                "durationAudioAll": 779,
                "durationVideo1080P": 0,
                "durationVideo2K": 0,
                "durationVideo4K": 0,
                "durationVideoHd": 60,
                "durationVideoHdp": 0
            }
        },
        {
            "date": "2021-10-14T00:00:00.000Z",
            "usage": {
                "durationAudioAll": 0,
                "durationVideo1080P": 0,
                "durationVideo2K": 0,
                "durationVideo4K": 0,
                "durationVideoHd": 0,
                "durationVideoHdp": 0
            }
        }
    ]
}

Response status codes

The following table shows the possible response status codes.

If the status code is 200 or 201, the request succeeds.
If the status code is neither 200 nor 201, the request fails. See the message field in the response body for the reason for this failure.

Response status code	Description
200	The request is successful.
201	The request has been fulfilled, resulting in the creation of a new resource.
400	Bad request. Possible reasons: Duplicate project name. Vendor is blocked. The number of projects exceeds the maximum limit.
401	Unauthorized (incorrect App ID/Customer Certificate).
403	Forbidden.
404	The requested resource could not be found.
415	Unsupported media type. Make sure that you set `Content-Type`in `Headers` as `application/json`.
429	Too many requests.
500	Internal error of the Agora RESTful API service.