The Rest API makes it possible to retrieve basic information from the server and also to call some functions. Before we can access the API, it must be configured properly via the preferences.xml file
<REST>
<IPWhiteList>192.168.0.1, 192.168.0.2</IPWhiteList>
<Authorization>
<auth username="admin" password="admin" />
</Authorization>
</REST>
There are two levels of authorization for REST-API. The first is IPWhiteList, which can contain multiple IP addresses separated by a comma (space is optional). The second one is the user list for basic auth. You can leave either IPWhiteList or Authorization empty if you wish. If both lists are empty, no authorization is required at all (we do not advise on doing this).
Here is an example on how to create a very simple request using PHP. We're using Basic Auth for authorization here.
$ch = curl_init("https://sub1.mydomain.com/rest-api/info");
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml', $additionalHeaders));
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "admin" . ":" . "admin");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($ch);
curl_close($ch);
Below you’ll find a list of available APIs for basic server management.
GET: /rest-api/info
{
"status": "success",
"version": "1.0.3", // server version
"branch": "main" // server branch (usually main or development)
"os": {
"name": "Mac OS X", // OS name
"version": "10.16" // OS version
},
"jvm": {
"vendor": "Oracle Corporation", // Vendor for JVM
"version": "13.0.1" // Java version
},
"hardware": {
"arch": "x86_64", // CPU architecture
"cpuCount": 16 // Number of processor units (including HT cores)
}
}
GET: /rest-api/server-load
{
"status": "success",
"cpu": {
"currLoad": 0.10, // Current CPU usage in %
"avgLoad": 1.20, // Average CPU usage in % (last minute)
},
"memory": {
"total": 65536, // Total system memory
"used": 30128, // Used system memory (total)
"free": 35407 // Free system memory (total)
"commited": 24658 // Memory assigned to server process
}
}
GET: /rest-api/server-stats
{
"status": "success",
"streams": 100, // Number of streams
"viewers": 10000, // Number of viewers
"uptime": 3600 // Number of seconds since player start
}
GET: /rest-api/applications-list
{
"status": "success",
"applicationList": ["live","test"], // List of all available applications
"applicationListSize": 2 // Number of items
}
GET: /rest-api/application/$applicationName
{
"status": "success",
"applicationName":"live" // Name of the application
"streamCount": 100, // Number of streams under this application
"viewerCount": 10000, // Number of viewers in streams of that application
"secureStream": {
"isEnabled": true, // Whenever secureStream option is enabled
"password": "qwerty", // Password for secureStream
"timeout": 5, // SecureStream timeout
},
"dvr": {
"isEnabled": false, // Whenever DVR option is enabled
"cacheSize": 45, // Cache duration in seconds
}
}
GET: /rest-api/streams-list/$applicationName
{
"status": "success",
"applicationName": "live", // Name of requested application
"streamsList": ["test_lq","test_hd"], // List of active broadcasts
"streamsListSize": 2 // Number of items
}
GET: /rest-api/stream/$applicationName/$streamName
{
"status": "success",
"streamName": "test", // stream name (published name)
"applicationName": "live", // application name
"startTime": 1626728976567, // when server was started(unix-time)
"viewers": 1, // current number of viewers
"source": {
"type": "RTMP_SERVER", // RTMP_SERVER for local streams and RTMP_client for external streams
"state": "STREAMING", // current state of the source e.g.: INITIATED, CONNECTED, STREAMING, CLOSED, NOT_FOUND, STARTED
"transportThreadStatus": "OK!", // This should always display "OK!"
"firstPacketTime": 1626728972080, // Time when first data packet arrived (unix-time)
"lastPacketDeltaTime": 7244, // Time of the last packet (combine with first packet time to get the actual time)
"receivedVideoPackets": 218, // Number of video data packets received
"receivedAudioPackets": 341, // Number of audio data packets received
"inboundBandwidth": 2341, // Incoming source bandwidth in kb/s
"metadata": {
"width": 1920, // Video width
"height": 1080, // Video height
"fps": 30, // Current FPS (Frames-per-seconds) count
"isVFR": false, // Whenever stream uses Variable Frame-Rate
"videoCodec": "H264", // Video codec
"audioCodec": "AAC", // Audio codec
"audioSampleRate": 48000, // Sample Rate for Audio
"audioSampleSize": 0, // Sample Size for Audio
"encoder": "obs-output module (libobs version 26.0.2)"
}
}
}
GET: /rest-api/stream-viewers-list/$applicationName/$streamName
{
"status": "success",
"streamName": "test", // stream name (published name)
"applicationName": "live", // application name
"viewersListSize": 1, // current number of viewers
"viewersList": [{"id:":1, "ip":"192.168.0.1"}]
}
GET: /rest-api/shutdown-server
{
command: "shutdown", // Command name
status: "success" // Action status
}
POST: /rest-api/register-group
Post fields:
command | registerStreamGroup |
groupName | A name for a group Name. For more reference please check Gateway configuration section. |
data | JSON source array. For more reference please check Gateway server section. |
{
command: "registerStreamGroup", // Command name
status: "success" // Action status
}
POST: /rest-api/unregister-group
Post fields:
command | unregisterStreamGroup |
groupName | A name for a group Name. For more reference please check Gateway configuration section. |
{
command: "unregisterStreamGroup", // Command name
status: "success" // Action status
}