Nimble Streamer Native API Reference

To make Nimble Streamer responding to API requests, the API settings must be set up in /etc/nimble/nimble.conf configuration file. You may check config description to get details about other parameters.
All parameters mentioned below are excluded from config by default.

management_listen_interfaces

This parameter specifies which IP addresses will be used for accepting API requests. If it's not set, the API requests are not accepted.

Examples:
management_listen_interfaces = * - all available interfaces are used
management_listen_interfaces = 127.0.0.1, 192.168.0.1

management_port

This one specifies which port is used to listen to API requests. If it's missing, the 8082 port is used.

Example:
management_port = 8086

management_token

This parameters specifies the token (i.e. password) which is used for authorizing API requests. See Making authorized requests section below for details.
If this parameter is missing, there will be no authorization made and anyone will be able to get information.

Example:
management_token = mypassword

This is an optional step for the cases when you use management_token parameter for authorizing requests. To make authorized requests you need to make MD5 hash based on the specified token.
Please refer to this code sample to see how you can generate this hash.

<?php
$salt= rand(0, 1000000);
$key = "mypassword"; // the token specified in management_token parameter
$str2hash = $salt . "/". $key;
$md5raw = md5($str2hash, true);
$base64hash = base64_encode($md5raw);
$request_url = "http://127.0.0.1:8082/manage/server_status?salt=$salt&hash=$base64hash";
echo $request_url;
?>

This API method allows getting current status of server instance.

Request URL:
/manage/server_status
Response parameters:

This method allows getting current status of outgoing streams for all supported protocols.
Note: /manage/rtmp_status is considered deprecated.

Request URL:
/manage/live_streams_status
Response parameters:

[
   {
      "app" : "live",
      "streams" : [
         {
            "acodec" : "mp4a.40.2",
            "vcodec" : "avc1.42c01f",
            "publish_time" : "1524060893",
            "bandwidth" : "1697348",
            "protocol" : "RTSP",
            "resolution" : "1280x720",
            "strm" : "stream_rtsp",
            "source_url" : "rtmp://127.0.0.1:1935/live/stream"
            "publisher_ip": "192.168.0.95",
            "publisher_port": 60349
         },
         {
            "vcodec" : "avc1.42c01f",
            "publish_time" : "1524060893",
            "acodec" : "mp4a.40.2",
            "strm" : "stream_rtmp",
            "bandwidth" : "1698536",
            "protocol" : "RTMP",
            "resolution" : "1280x720",
            "publisher_ip" : "127.0.0.1"
         },
         {
            "vcodec" : "avc1.64001e",
            "publish_time" : "1524060893",
            "bandwidth" : "286200",
            "resolution" : "640x360",
            "protocol" : "ENCODER",
            "strm" : "stream_360p"
         }
      ]
   }
]

This method allows getting the list of all active end-user sessions. So whoever is watching or listening streams, their sessions will be shown.
This allows collecting and analysing current viewers and gather basic stats. You can also disconnect any of these sessions using /manage/sessions/delete method.

Request URL:
/manage/sessions
Response parameters:

[
  {
    "id":4,
    "app":"live",
    "stream":"stream",
    "type":"HLS",
    "created":1654499440,
    "last_access":1654499466,
    "client_ip":"127.0.0.1",
    "user_agent":"Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/102.0.0.0 Safari\/537.36"
  }
]

This method allows deleting any specific session or sessions based on the IDs from /manage/sessions method.
When HLS or MPEG-DASH session is deleted, a client gets 403 HTTP response. For other protocols, (MPEG-TS/Icecast/RTMP/RTSP/SRT) the client is just disconnected.

Request URL:
/manage/sessions/delete
Request parameters:

{"status":"Ok"}

This method allows getting settings of RTMP streaming.

Request URL:
/manage/rtmp_settings
Response parameters:They are nested under RtmpSettings node.

{
  "RtmpSettings": {
    "hash":"1414983917310",
    "interfaces":[
      {
        "ip":"*",
        "port":1936
      }
    ],
    "login":"",
    "password":"",
    "duration":6,
    "protocols":["HLS"],
    "apps":[],
    "abr":[
      {
        "app":"nimble_live_abr",
        "stream":"abrstream",
        "streams":[
          {
            "app":"live",
            "stream":"stream"
          }
        ]
      }
    ]
  }
}

This GET method allows getting current status of RTMP streams re-publishing.

Request URL:
/manage/rtmp/republish/stats
Response parameters: All are nested under "stats" node.

{
 "stats" : [
    {
       "bandwidth" : 613564,
       "bytes_recv" : 3485,
       "bytes_sent" : 8166049,
       "dest_addr" : "127.0.0.1",
       "dest_app" : "live-re",
       "dest_port" : 1999,
       "dest_stream" : "dest_stream",
       "owner" : 1,
       "retry_count" : 1,
       "rule_id" : "1",
       "session_duration" : 102,
       "src_app" : "live",
       "src_stream" : "stream",
       "state" : "connected"
    }
 ],
 "status" : "Ok"
}

This GET method allows getting list of RTMP streams re-publishing rules which were created via Nimble API only.
For full list please refer to WMSPanel control API reference.

Request URL:
/manage/rtmp/republish
Response parameters:
All are nested under "rules" node, with each rule having its nested node. Another node is "status" which indicates the status of request.

{
   "rules" : [
      {
         "auth_schema" : "NONE",
         "dest_addr" : "127.0.0.1",
         "dest_app" : "live-re",
         "dest_app_params" : "",
         "dest_login" : "",
         "dest_password" : "",
         "dest_port" : 1999,
         "dest_stream" : "stream1",
         "dest_stream_params" : "",
         "id" : "1",
         "keep_src_stream_params" : false,
         "src_app" : "live",
         "src_stream" : "stream",
         "ssl" : false
      },
      {
         "auth_schema" : "NONE",
         "dest_addr" : "127.0.0.1",
         "dest_app" : "live-re",
         "dest_app_params" : "",
         "dest_login" : "",
         "dest_password" : "",
         "dest_port" : 1999,
         "dest_stream" : "stream2",
         "dest_stream_params" : "",
         "id" : "2",
         "keep_src_stream_params" : false,
         "src_app" : "live",
         "src_stream" : "stream",
         "ssl" : false
      }
   ],
   "status" : "Ok"
}

This GET method allows getting certain RTMP stream re-publishing rule.

Request URL:
/manage/rtmp/republish/<id>
Request parameters:
All are nested under "rules" node, with each rule having its nested node. Another node is "status" which indicates the status of request.

{
   "rules" : [
      {
         "auth_schema" : "NONE",
         "dest_addr" : "127.0.0.1",
         "dest_app" : "live-re",
         "dest_app_params" : "",
         "dest_login" : "",
         "dest_password" : "",
         "dest_port" : 1999,
         "dest_stream" : "stream1",
         "dest_stream_params" : "",
         "id" : "1",
         "keep_src_stream_params" : false,
         "src_app" : "live",
         "src_stream" : "stream",
         "ssl" : false
      }
   ],
   "status" : "Ok"
}

This POST method allows creating a new RTMP re-publishing rule.
Notice that re-publishing setting defined by this API call are not persistent and they are reset after Nimble Streamer re-load. If you'd like to keep them, you should use WMSPanel control API instead.

Request URL:
/manage/rtmp/republish
Request parameters:

{
  "status": "Ok",
  "rule":{
    "id":"1",
    "dest_addr":"127.0.0.1",
    "dest_port":1999,
    "src_app":"live",
    "dest_app":"live-re",
    "src_stream":"stream",
    "dest_stream":"dest_stream",
    "dest_app_params":"",
    "dest_stream_params":"",
    "dest_login":"",
    "dest_password":"",
    "ssl":false,
    "keep_src_stream_params":false,
    "auth_schema":"NONE"
  }
}

This DELETE method allows deleting specified setting of RTMP stream re-publishing.
Notice that re-publishing setting defined by this API call are not persistent and they are reset after Nimble Streamer re-load. If you'd like to keep them, you should use WMSPanel control API instead.

Request URL:
/manage/rtmp/republish/<id>
Response parameters: Response has "status" filed with either "Ok" or "NotFound".

Request example:
curl -X DELETE http://127.0.0.1:8082/manage/rtmp/republish/1
Response example:

{"status": "Ok"}
or
{"status": "NotFound"}

This method allows getting the current status of MPEG-TS incoming streams (from "MPEGTS In" settings section).

Request URL:
/manage/mpeg2ts_status
Response parameters:
Depend on type of the stream, fields will be similar to other calls' fields.

Request example:
curl -vvv http://127.0.0.1:8082/manage/mpeg2ts_status

This method allows getting current status of MPEG-TS streaming.

Request URL:
/manage/mpeg2ts_settings
Response parameters:
Depend on type of the stream, fields will be similar to other calls' fields.

Request example:
curl -vvv http://127.0.0.1:8082/manage/mpeg2ts_settings
Response example:

{
  "CamerasHash": "1623888659745",
  "Cameras": [
    {
      "id": "60cabad9f776481a8719c760",
      "ip": "192.168.0.1",
      "port": 3131,
      "protocol": "udp"
    },
    {
      "id": "60307b55f7764826190e3c31",
      "ip": "0.0.0.0",
      "port": 49002,
      "protocol": "srt",
      "receive_mode": "listen"
    },
    {
      "id": "5f76b049f776487f9fca1d16_1621821016071",
      "ip": "0.0.0.0",
      "port": 49101,
      "protocol": "rist",
      "receive_mode": "listen",
      "parameters": [
        {
          "name": "rist-logging",
          "value": "debug"
        },
        {
          "name": "rist-stats-interval",
          "value": "15"
        }
      ]
    }
  ]
}

These methods allow getting current sender and receiver stats for SRT streams.

Request URL:
/manage/srt_sender_stats
/manage/srt_receiver_stats
Response parameters:
Returned fields are defined by SRT protocol spec.

Requests examples:
curl -vvv http://127.0.0.1:8082/manage/srt_sender_stats
curl -vvv http://127.0.0.1:8082/manage/srt_receiver_stats

This method allows getting list of NDI streams available on the server.

Request URL:
/manage/ndi/list
Requests examples:
curl -vvv http://127.0.0.1:8082/manage/ndi/list

These methods allow getting current sender and receiver stats for RIST streams.
In order to use these API calls, you need to add "rist-stats-interval" parameter into RIST output and input respectively, setting interval in seconds.

Request URL:
/manage/rist_sender_stats
/manage/rist_receiver_stats
Response parameters:
Returned fields are defined by RIST protocol spec.

Requests examples:
curl -vvv http://127.0.0.1:8082/manage/rist_sender_stats
curl -vvv http://127.0.0.1:8082/manage/rist_receiver_stats

This API method allows getting information about existing Icecast stream. Response parameters are taken from Icecast metadata settings, most of which can be set up via WMSPanel UI.

Request URL:
/manage/icecast_stream_info/application_name/stream_name
Response parameters:

This POST method injects Icecast metadata into /<app>/<stream> RTMP stream.
Read Manual ingest of Icecast metadata into RTMP via API article for more details.
Request URL:
/manage/icecast_metadata/<app>/<stream>
Request example:
curl -vvv http://127.0.0.1:8083/manage/icecast_metadata/live/radio -d "{\"streamtitle\":\"title\", \"streamurl\":\"url\"}"
Response example:
{"status": "Ok"}

This POST method triggers insertion for SCTE35 Out marker into /<app>/<stream> if that stream is configured with "time_sync":"scte35" in Nimble Advertizer. It also allows setting the "duration" parameter to set the time in seconds for returning from ads.
Read SCTE-35 marker insertion article and Nimble Advertizer spec for more details.
Notice that this feature requires Addenda license to operate.
Request URL:
/manage/advertizer/scte35_out/<app>/<stream>[?duration=<time>]
Request examples:
curl -vX POST http://127.0.0.1:8083/manage/advertizer/scte35_out/live/stream1
curl -vX POST http://127.0.0.1:8083/manage/advertizer/scte35_out/live/stream2?duration=10
Response example:
{"status": "Ok"}

This POST method triggers insertion for SCTE35 In marker into /<app>/<stream> if that stream is configured with "time_sync":"scte35" in Nimble Advertizer.
Read SCTE-35 marker insertion article and Nimble Advertizer spec for more details.
Request URL:
/manage/advertizer/scte35_in/<app>/<stream>
Request example:
curl -vX POST http://127.0.0.1:8083/manage/advertizer/scte35_in/live/stream
Response example:
{"status": "Ok"}

This method allows getting the status of output streams generated by Server Playout feature set.

Request URL:
/manage/server_playlist_status
Response parameters:

[
  {
    "stream": "live/first_playlist",
    "block_id": "33",
    "block_duration": 45,
    "main_stream": "live/stream1",
    "main_stream_type": "live",
    "main_stream_duration": 45,
    "default_stream": "/home/content/mp4/sample.mp4",
    "default_stream_type": "vod",
    "default_stream_duration": 45
  }
 ,
  {
    "stream": "live/second_playlist",
    "block_id": "33",
    "block_duration": 113,
    "main_stream": "live/stream2",
    "main_stream_type": "live",
    "main_stream_duration": 113
  }
]

Please refer to Server Playout specification for more details about the feature set and the meaning of each parameter.

This method allows getting the status of published streams as part of publish control framework for RTMP and RTSP published streams.

Request URL:
/manage/publish_control/status
Response parameters:

{
  "PublishControlStatus":
  [
    {"key":"1", "id":"ID_1", "ip":"192.168.1.1","stream":"live/stream1"},
    {"key":"2", "id":"ID_2", "ip":"192.168.1.2","stream":"live/stream2"}
  ]
}

Please refer to publish control framework description for more details.

This method sends to Nimble Streamer a list of blocked sessions. It's a POST request.
This is part of publish control framework for RTMP and RTSP published streams.

Request URL:
/manage/publish_control/deny
Request parameters:

Please refer to publish control framework description for more details.

This method allows getting list of the DVR archives (or archive for specified stream) and their detailed info.

Request URL:
/manage/dvr_status[/application/stream]
Request parameters:

[
   {
      "size" : 11333929,
      "bandwidth" : 1619128,
      "resolution" : "1080x608",
      "periods" : 1,
      "stream" : "live/stream1",
      "acodec" : "mp4a.40.2",
      "vcodec" : "avc1.4d401f",
      "path" : "/var/cache/nimble/dvr/live/stream1",
      "duration" : 56,
      "space_available" : 57962266624,
      "timeline" : [
         {
            "duration" : 56,
            "start" : 1470753122
         }
      ]
   },
   {
      "size" : 22041265,
      "bandwidth" : 1663488,
      "resolution" : "1080x608",
      "periods" : 2,
      "stream" : "live/stream2",
      "acodec" : "mp4a.40.2",
      "vcodec" : "avc1.4d401f",
      "space_available" : 57962266624,
      "path" : "/var/cache/nimble/dvr/live/stream2",
      "duration" : 106,
      "timeline" : [
         {
            "start" : 1470753194,
            "duration" : 53
         },
         {
            "duration" : 53,
            "start" : 1470753378
         }
      ]
   }
]

This method allows getting MP4 file for DVR archive for specified stream.

Request URL:
/manage/dvr/export_mp4/application/stream[?start=&end=]
Request parameters:

This POST method allows cleaning the DVR archive for designated stream.

Request URL:
/manage/dvr/cleanup_archive/application/stream
Request parameters:

This GET method allows getting a cache key for any item in Nimble cache for further removal. This relates to re-streaming use cases (including remote VOD).

Request URL:
/manage/data_cache/get_key
Request parameters:

This POST method deletes all items from Nimble cache by a cache key. This relates to re-streaming use cases (including remote VOD). For HLS items it deletes a playlist, chunk lists and chunks related to specified file.

Request URL:
/manage/data_cache/delete
Request parameters:

This POST method allows reloading SSL certificates.

Request URL:
/manage/reload_ssl_certificates
Request example:
curl -X POST http://127.0.0.1:8082/manage/reload_ssl_certificates

This POST method forces Nimble Streamer to reload config from WMSPanel.

Request URL:
/manage/sync_panel_settings
Request example:
curl -X POST http://127.0.0.1:8083/manage/sync_panel_settings

This POST method allows reloading Nimble Streamer config without restarting server. By default, only rules.conf is reloaded. If you want to reload drm.conf to apply new DRM settings on-the-fly, add drm=true parameter as shown below.

Request URL:
/manage/reload_config[?drm=true]
Request example:
curl -X POST http://127.0.0.1:8083/manage/reload_config