Documentation
Agora Basics
Console 官网 Community Technical support
English
search-icon

Console RESTful APIs

Last updated 2022/04/26 03:55:20

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.

Authentication

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. See HTTP authentication.

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. If you are frequency limited when calling the APIs, please see How can I avoid being frequency limited when calling Agora Server RESTful APIs to optimize API call frequency.

Creates a project

Creates an Agora project.

You can create up to 10 projects, including previously deleted ones. If you need to create more projects, please contact us by submitting a ticket.

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

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

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

    Disables or enables 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
    }
}

    Sets the IP address of the recording server

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

    This API is only compatible with v1.9.0 and earlier versions of the Agora On-premise Recording SDK.

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

    Enables or disables 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 (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
    }
}

    Resets the primary app certificate

    Resets the primary app certificate for a specified project.

  • If the primary app certificate is leaked, use this method to reset it.
  • If the primary app certificate has not been enabled, calling this method automatically enables it.

    • 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
    }
}

    Gets project usage

    Gets the usage data of a specified project.

  • Ensure that you fill in a valid project ID; otherwise, you cannot get the usage data.
  • You can only get the usage data for the past 12 months.
  • Agora recommends not including the current day in your query period, because the data is continuously changing on the current day.

    • 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 (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-Typein Headers as application/json.
    429 Too many requests.
    500 Internal error of the Agora RESTful API service.