Developers API
Developers can use the API to programmatically interact with Streams.
Authentication
Authenticate with the API by providing an Authorization:Bearer header with each request.
Request Headers
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | An authorization bearer token. |
Authorization: Bearer your_authorization_token
Get Authorization token
Use an API key to authenticate with the API.
Request
Method: POST
Content-Type: application/json
https://stream.gradedblue.com/api/v1/auth/authorizeRequest Body
| Parameter | Type | Description |
|---|---|---|
| apiKey | string | An API key generated in the dashboard. |
{
"apiKey": "AE0u-NfkwD...nbA9HrYPBW"
}
Response
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| authorizationToken | string | A short-lived authorization bearer token. |
| expiresIn | number | The number of seconds in which the token expires. |
{
"authorizationToken": "eyJhbGciOi...C0dLLvQB9Q",
"expiresIn": 3600
}
List Regions
Get a list of region IDs.
Request
Method: GET
https://stream.gradedblue.com/api/v1/regionsResponse
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| regions | array | A list of all available region IDs. |
{
"regions": [
"lhr",
"ams",
"fra",
"cdg",
"atl",
"dfw",
"lax",
"yto",
"nrt",
"icn",
"sgp",
"syd"
]
}
Get Plans
Get all plans and their details.
Request
Method: GET
https://stream.gradedblue.com/api/v1/plansResponse
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| plans | object | A map of all available plans. |
| plans.{planId} | object | Contains details on the plan's restrictions. |
| plans.{planId}.maxClients | number | The maximum receiving clients. |
| plans.{planId}.maxResolution | object | A maxResolution object. |
| plans.{planId}.maxResolution.width | number | The maximum width in pixels. |
| plans.{planId}.maxResolution.height | number | The maximum height in pixels. |
| plans.{planId}.maxFrameRate | number | The maximum frames per second. |
| plans.{planId}.maxBitrate | number | The maximum bitrate in Kbps. |
{
"plans": {
"basic": {
"maxClients": 3,
"maxResolution": {
"width": 1280,
"height": 720
},
"maxFrameRate": 60,
"maxBitrate": 7000
},
"standard": {
"maxClients": 6,
"maxResolution": {
"width": 1920,
"height": 1080
},
"maxFrameRate": 60,
"maxBitrate": 10000
},
"pro": {
"maxClients": 12,
"maxResolution": {
"width": 3840,
"height": 2160
},
"maxFrameRate": 60,
"maxBitrate": 55000
}
}
}
List Streams
Get a list of streamIds for all active subscriptions.
Request
Method: GET
https://stream.gradedblue.com/api/v1/streamResponse
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| streams | array | A list of all streamIds associated with your account. |
{
"streams": [
"sub_Hqc6U5q2bIw1h3",
"sub_HquS3f7Vgy7N22",
"sub_Ht9WxVaXVo09zU",
"sub_HtzaZpgkT1DyRh",
"sub_HylOoAUNoy0bkz",
"sub_HylPhKo8NoBpWM"
]
}
Get Stream Info
Get the details of a specific stream.
Request
Method: GET
https://stream.gradedblue.com/api/v1/stream/{streamId}Response
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| name | string | A list of all streamIds associated with your account. |
| key | string | The stream key. |
| region | string | The stream's region ID. |
| ingest | string | Ingest server URL. |
| output | string | Output stream URL. |
| renewing | boolean | If the stream will renew at the end of the billing period. |
| plan | string | The plan name. One of 'basic', 'standard' or 'pro'. |
| timing | object | A timing object. Values in seconds from the unix epoch. |
| timing.created | number | When the stream was created. |
| timing.expires | number | When the stream renews/expires. |
{
"name": "Pro AMS",
"key": "85276a675940d3afab547c5f25ca96ae84a437a6d436cbbe2d",
"region": "ams",
"ingest": "rtmp://stream-ams1.graded.blue/live",
"output": "rtmp://stream-ams1.graded.blue/live/85276a675940d3afab547c5f25ca96ae84a437a6d436cbbe2d",
"renewing": true,
"plan": "pro",
"timing": {
"created": 1599498693,
"expires": 1602090693
}
}
Regenerate Stream Key
Regenerate the key for a stream. Any active clients will be disconnected.
Request
Method: POST
https://stream.gradedblue.com/api/v1/stream/{streamId}/regenResponse
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| key | string | The new stream key. |
{
"key": "1b50951d0611f564a5cae4b73e45e9d59a56ae04dd07674a3c"
}