Domain names

There are two types of domain names: stream-pushing domain names and stream-playing domain names (which mainly affect regional access and the deployment of the streams). The same live stream can be pushed or played through multiple different domain names.

The domain name management function is in the beta stage. Contact sales@agora.io before using it.

Add domain names

Add a stream domain name.

When adding a domain name, you need to specify the App ID of your Agora project.

HTTP request

POST https://api.agora.io/v1/projects/{appid}/fls/domains?id={domain}

Path parameter

appid: String type, required. The App ID provided by Agora for each developer. You can get an App ID after creating a project in the Agora Console. The App ID is the only identification of a project.

Query parameters

id: String type, required. The domain name to be added. Pan-domain names are not supported.

Request body

The request body is the data field in the JSON Object type, and contains the following fields:

Field	Type	Description
`type`	String	Required. The domain name type: `"publish"`: The stream-pushing domain name. `"play"`: The stream-playing domain name.
`region`	String	Required when the domain name type is set as `"publish"`. This parameter only applies to stream-pushing domain names. The region of the Agora server used for the stream-pushing domain name: `"cn"`: China Mainland. `"ap"`: Asian regions except for China Mainland. `"eu"`: Europe. `"na"`: North America.

HTTP response

If the returned HTTP status code is 201, the request is successful, and the response body contains the following fields:

Field	Type	Description
`appid`	String	The App ID of your Agora project.
`type`	String	Set the domain name type: `"publish"`: The stream-pushing domain name. `"play"`: The stream-playing domain name.
`region`	String	Set the region where the Agora server is located. Only returned when the `type` is `"publish"`.
`authKey`	String	The authentication key for hotlink protection.
`cname`	String	The cname corresponds to the domain name, and you need to configure it at your DNS host.

If the returned HTTP status code is not 201, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

POST https://api.agora.io/v1/projects/{your_appid}/fls/domains?id={your_domain} HTTP/1.1

Request body

{
    "region": "cn",
    "type": "publish"
}

Response line

HTTP/1.1 201 Created

Request body

{
    "appid": "{your appid}",
    "name": "{your domain}",
    "region": "cn",
    "type": "publish"
}

Delete domain names

Delete a stream domain name.

HTTP request

DELETE https://api.agora.io/v1/projects/{appid}/fls/domains/{domain}

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID corresponding to the domain name being deleted.
`domain`	String	Required. The domain name being deleted.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

DELETE https://api.agora.io/v1/projects/{your_appid}/fls/domains/{your_domain} HTTP/1.1

Response line

HTTP/1.1 200 OK

Get domain name lists

Get all stream domain names under one Agora project.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/domains

Path parameter

appid: String type, required. The App ID of your Agora project

HTTP response

If the returned HTTP status code is 200, the request is successful, and the response body contains the following fields:

domainList: JSON Array type, the domain name list. One stream corresponds to a JSON Object, and contains the following fields:

Field	Type	Description
`appid`	String	The App ID of your Agora project.
`name`	String	The domain name.
`type`	String	The domain name type. `"publish"`: The stream-pushing domain name. `"play"`: The stream-playing domain name.
`region`	String	The region of the Agora server used for the domain name. Only returned when the `type` is `"publish"`.
`authKey`	String	The authentication key for hotlink protection.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

GET https://api.agora.io/v1/projects/{your_appid}/fls/domains HTTP/1.1

Response line

HTTP/1.1 200 OK

Request body

{
    "domainList": [
        {
            "appid": "{your appid}",
            "authKey": "{your authkey}",
            "name": "{your play domain}",
            "type": "play"
        },
        {
            "appid": "{your appid}",
            "authKey": "{your authkey}",
            "name": "{your publish domain}",
            "region": "cn",
            "type": "publish"
        }
    ]
}

Get domain name attributes

Get the attributes of the specified domain name.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/domains/{domain}

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID corresponding to the domain name being queried.
`domain`	String	Required. The domain name being queried.

HTTP response

If the returned HTTP status code is 200, the request is successful, and the response body contains the following fields:

Field	Type	Description
`appid`	String	The App ID of your Agora project.
`name`	String	The domain name.
`type`	String	The domain name type. `"publish"`: The stream-pushing domain name. `"play"`: The stream-playing domain name.
`region`	String	The region of the Agora server used for the domain name. Only returned when the `type` is `"publish"`.
`authKey`	String	The authentication key for hotlink protection.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

GET https://api.agora.io/v1/projects/{your_appid}/fls/domains?id={your_domain} HTTP/1.1

Response line

HTTP/1.1 200 OK

Request body

{
    "appid": "{your appid}",
    "authKey": "{your authkey}",
    "name": "{your domain}",
    "region": "cn",
    "type": "publish"
}

HTTP status code

Status code	Description
200	The request succeeds.
400	The parameter is invalid, for example the `appid` or the `entry_point` is empty, or the `region` parameter value is invalid.
401	Unauthorized (the customer ID and the customer secret do not match).
404	The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500	An internal error occurs in the server, so the server is not able to complete the request.
504	An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.