Bypass Live Push-Stream RESTful API

Introduction

This document describes the specification and usage of the broadcasting channel RESTful API.

Authorization

To ensure security, use Channel Key when calling API in this document. For details on how to generate a Channel Key, refer to Obtaining and Using a Dynamic Key .

Note

Be sure that you set the uid as 0 when generating a Channel Key according to Obtaining and Using a Dynamic Key .

Enum Definition

Code Description
200 OK
400 Invalid Request Parameter
401 Unauthorized request
404 The requested channel does not exist
409 Conflicted channel names

Footnotes

[1]400 will return lots of other difference messages except for “Bad Request”. Generally speaking, when 400 is returned, it means the request is invalid.

Start Pushing Stream(POST)

This REST method POST starts to push stream.

URL

http://broadcastgw.agora.io/api/v1/channel

Query Parameters

Name Type Optional Array Description Default
cname string No No Channel name
urls string Yes Yes Array of stream URLs “”
channelkey string No No Channel Key for authorization

Format

{
        "cname": "",
        "urls": [""],
        "channelkey": ""
}

Example

{
        "cname": "channel",
        "urls": ["rtmp://agora.io/stream1", "rtmp://agora.io/stream2"]
        "channelkey": "0046b5491695dde1a8a0671afaf93f35583ffdf892c4ace618eb6fb4755861a6008b801a4101476155695bf6f0a420000000000"
}

Success Callback: Push Stream Started

Code: 200

Name Type Array Description
cname string No Channel name
uids int Yes The order of the hosts by ID
urls string No Array of stream urls

Format

{
          "data": {
                  "cname": "",
                  "uids": [ ],
                  "urls": [""]
          }
}

Example

{
          "data": {
                  "cname": "channel",
                  "uids": [6496936, 6285261],
                  "urls": ["rtmp://agora.io/stream1", "rtmp://agora.io/stream2"]
          }
}

Error Callback: Failed to Push Stream

Code: 400

{
          "error": {
                  "code": 400,
                  "message": "Invalid request parameter"
          }
}

Code: 401

{
          "error": {
                  "code": 401,
                  "message": "Unauthorized"
          }
}

Update Push-Stream Information(PUT)

This REST method PUT updates the push-stream information, for example, update the host uid or the original push-stream URL of the host.

URL

http://broadcastgw.agora.io/api/v1/channel

Query Parameters

Name Type Optional Array Description
cname string No No Channel name
uids int Yes Yes The order of the hosts by ID
urls string Yes Yes The array of the stream urls
channelkey string No No Channel Key for authorization

Format

{
        "cname": "",
        "uids": [ ],
        "urls": [""],
        "channelkey": ""
}

Example

{
  "cname": "channel",
  "uids": [6496936, 6285261],
  "urls": ["rtmp://agora.io/stream1", "rtmp://agora.io/stream2"],
  "channelkey": "0046b5491695dde1a8a0671afaf93f35583ffdf892c4ace618eb6fb4755861a6008b801a4101476155695bf6f0a420000000000"
}

Success Callback: Push-Stream Information Updated

This section shows the success response when the push-stream information is updated:

Code: 200

Name Type Array Description
cname string No Channel name
uids int Yes The order of the hosts by ID
urls string Yes The array of the stream urls

Format

{
      "data": {
              "cname": "",
              "uids": [ ],
              "urls": [""]
      }
}

Example

{
      "data": {
              "cname": "channel1",
              "uids": [6496936, 6285261],
              "urls": ["rtmp://agora.io/stream1", "rtmp://agora.io/stream2"]
      }
}

Error Callback: Failed to Update Push-Stream Information

This section shows the error response when the you failed to update the push-stream information:

Code: 400

{
        "error": {
                "code": 400,
                "message": "Invalid request parameter"
        }
}

Code: 401

{
      "error": {
              "code": 401,
              "message": "Unauthorized"
      }
}

Code: 404

{
      "error": {
              "code": 404,
              "message": "Channel not found"
      }
}

Stop Pushing Stream(DELETE)

This REST method DELETE stops pushing stream.

URL

http://broadcastgw.agora.io/api/v1/channel

Query Parameters

Name Type Optional Array Description
cname string No No Channel name
channelkey string No No Channel Key for authorization

Format

{
        "cname": "",
   "channelkey": ""
}

Example

{
        "cname": "channel",
        "channelkey": "0046b5491695dde1a8a0671afaf93f35583ffdf892c4ace618eb6fb4755861a6008b801a4101476155695bf6f0a420000000000"
}

Success Callback: Push-Stream Stopped

This section shows the success response when the push-stream is stopped:

Code: 200

Name Type Array Description
cname string No Channel name

Format

{
        "data": {
                "cname": ""
        }
}

Example

{
        "data": {
                "cname": "channel"
        }
}

Error Callback: Failed to Stop Pushing Stream

This section shows the error response when the push-stream fails to stop:

Code: 400

{
        "error": {
                "code": 400,
                "message": "Invalid request parameter"
        }
}

Code: 401

{
        "error": {
                "code": 401,
                "message": "Unauthorized"
        }
}

Code: 404

{
        "error": {
                "code": 404,
                "message": "Channel not found"
        }
}