Pull-from-origin

Pull-from-origin means that after receiving a playback request from a viewer, the Agora servers pull streams from your origin server and deliver the content to the viewer. You can use the pull-from-origin function in one of the following ways:

Direct pull: When a playback request is received, Agora directly pulls streams from the origin server you set.
Dynamic pull: When a playback request is received, Agora first sends a request to your callback URL to get the origin server address, and then pulls streams from the address.

Set pull-from-origin configuration

Sets the pull-from-origin configuration for the specified entry point.

HTTP request

PATCH https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/origin_site

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

Request body

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

Field	Type	Description
`enabled`	Boolean	Optional. Whether to enable pull-from-origin.
`domain`	String	Optional. The domain name of your origin server, which is used for direct pull. This field and the `callbackUrl` field cannot be set at the same time.
`app`	String	Optional. The entry point (also known as the application name or AppName) of your origin server. This field must be set together with the `domain` field. If this field is left blank or set to empty, the entry point in the playback URL is used.
`callbackUrl`	String	Optional. Your callback URL, which is used for dynamic pull. This field and the `domain` field cannot be set at the same time.

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

PATCH https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/origin_site HTTP/1.1

Request body

{
    "enabled": true,
    "domain": "{your_domain}"
}

Response line

HTTP/1.1 200 OK

Get pull-from-origin configuration

Gets the pull-from-origin configuration of the specified entry point.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/origin_site

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

HTTP response

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

enabled: Boolean. Optional. Whether pull-from-origin is enabled.
domain: String. Optional. The domain name of your origin server, which is used for direct pull.
app : String. Optional. The entry point of your origin server.
callbackUrl: String. Optional. Your callback URL, which is used for dynamic pull.

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/entry_points/live/settings/origin_site HTTP/1.1

Request body

{
    "enabled": true,
    "domain": "{your_domain}"
}

Response line

HTTP/1.1 200 OK

Pull-from-origin callback requirements

If you specify callbackUrl when calling the Set pull-from-origin configuration API, Agora sends requests to this URL to get your origin server addresses. The request sent by Agora has the following format:

GET https://example.origin-site.com/entry_point={entry_point}&stream_name={stream_name} HTTP/1.1

Where the following parameters are replaced according to the playback URL:

entry_point : Replaced with the entry point in the playback URL.
stream_name: Replaced with the stream name in the playback URL.

For such a request, the HTTP response you return must meet the following requirements:

The response is in JSON format.
If the request succeeds, the HTTP status code is 200.
The origin server addresses are included in the url field in the response body:
_3{ _3 "url": "rtmp://cdna.example.com/live/testedge" _3}

Dynamic pull currently only supports RTMP streams.

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.