API Access

Your [API KEY] can be found in API in the dashboard menu. Responses to HTTP Requests return as JSON strings. Group Key can be found in the Settings window.

[API KEY] Can also be your logged in auth_token as well as the API Access key.

Login by API - Get Temporary API Key

Provide your login credentials. machineID can be anything.

$.post('http://xxx.xxx.xxx.xxx/?json=true',{machineID: "fMUVxYdG1X3hWb7GNkTd", mail: "[email protected]", pass: "123", function: "dash"},function(d){
     console.log(d.$user)
})
  • mail : Address used to login.
  • pass : Password associated to the account being used to login.
  • ke : Group Key, this can be found in Settings.
  • machineID : The unique string used to identify a machine when using 2-Factor Authentication.

If you have 2-Factor Authentication enabled you will need to pass a second gate. machineID must be the same as the one used at the first gate.

$.post('http://xxx.xxx.xxx.xxx/?json=true',{ke: "2Df5hBE", id: "XDf5hB3", machineID: "fMUVxYdG1X3hWb7GNkTd", factorAuthKey: "123456"},function(d){
     console.log(d.$user)
})
  • id : User ID, this can be found after login.
  • factorAuthKey : The key you will receive to pass the verification for your account.

Get Streams

Get a Monitor object and it will have a set of stream links already pre-built in the streams variable.

http://xxx.xxx.xxx.xxx/[API KEY]/monitor/[GROUP KEY]/[MONITOR ID]

JPEG Snapshot. Snapshot must be enabled in Monitor Settings.

http://xxx.xxx.xxx.xxx/[API KEY]/jpeg/[GROUP KEY]/[MONITOR ID]/s.jpg

MJPEG Stream. Stream type must be MJPEG.

http://xxx.xxx.xxx.xxx/[API KEY]/mjpeg/[GROUP KEY]/[MONITOR ID]

MJPEG for iframe.

http://xxx.xxx.xxx.xxx/[API KEY]/mjpeg/[GROUP KEY]/[MONITOR ID]?full=true

m3u8 for HLS Stream. Stream type must be HLS.

http://xxx.xxx.xxx.xxx/[API KEY]/hls/[GROUP KEY]/[MONITOR ID]/s.m3u8

FLV Stream. Stream type must be FLV.

http://xxx.xxx.xxx.xxx/[API KEY]/flv/[GROUP KEY]/[MONITOR ID]/s.flv

Poseidon (MP4) Stream. Stream type must be Poesidon.

http://xxx.xxx.xxx.xxx/[API KEY]/mp4/[GROUP KEY]/[MONITOR ID]/s.mp4

Stream Channels

Below is the link for a Poseidon stream but on a channel aside from the Main one. You can create Stream Channels by opening your Monitor Settings, clicking Options, and then selecting Add Channel.
http://xxx.xxx.xxx.xxx/[API KEY]/mp4/[GROUP KEY]/[MONITOR ID]/[CHANNEL]/s.mp4

Getting Monitors

Get all saved monitors

http://xxx.xxx.xxx.xxx/[API KEY]/monitor/[GROUP KEY]

This method will get all started monitors

http://xxx.xxx.xxx.xxx/[API KEY]/smonitor/[GROUP KEY]

Get a single monitor by ID

http://xxx.xxx.xxx.xxx/[API KEY]/monitor/[GROUP KEY]/[MONITOR ID]

Get all available h.264 streams in an .m3u8 playlist.

Enable the TV Channel option in your monitor's settings to see their streams in this list.
http://xxx.xxx.xxx.xxx/[API KEY]/tvChannels/[GROUP KEY]

Get a single monitor's available h.264 streams in an .m3u8 playlist.

Enable the TV Channel option in your monitor's settings to see their streams in this list.
http://xxx.xxx.xxx.xxx/[API KEY]/tvChannels/[GROUP KEY]

Getting Videos

Get videos for group key

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]

Get videos for monitor ID

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]

Get video file

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]/[FILENAME]

Get video files after start time

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]?start=YYYY-MM-DDTHH:mm:ss

Get video files before end time

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]?end=YYYY-MM-DDTHH:mm:ss

Get video files between start time and end time

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]?start=YYYY-MM-DDTHH:mm:ss&end=YYYY-MM-DDTHH:mm:ss

Get video files with custom start operator

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]?start=YYYY-MM-DDTHH:mm:ss&startOperator=>=

Get video files with custom end operator

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]?end=YYYY-MM-DDTHH:mm:ss&endOperator=<=

Get video files with time restrictions as startFrom and startTo

Normally the end parameter correlates directly to the end time of the video. This way you are searching only with start times.
http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]?start=YYYY-MM-DDTHH:mm:ss&end=YYYY-MM-DDTHH:mm:ss&endIsStartTo

Get Cloud Videos for group key

videos is interchangeable with cloudVideos. All the methods above this one can use the cloudVideos parameter. This API method only shows videos if you have saved videos with one of the provided Cloud Backup methods such as Amazon S3, Backblaze B2, and WebDAV.
http://xxx.xxx.xxx.xxx/[API KEY]/cloudVideos/[GROUP KEY]

Zip and download multiple videos

http://xxx.xxx.xxx.xxx/[API KEY]/zipVideos/[GROUP KEY]?videos=[{"filename":"YYYY-MM-DDTHH-mm-ss.mp4","mid":"[MONITOR ID]"},{"filename":"YYYY-MM-DDTHH-mm-ss.mp4","mid":"[MONITOR ID]"}]

System Triggers

FFprobe

Probe a camera URL to get stream specifications.
http://xxx.xxx.xxx.xxx/[API KEY]/probe/[GROUP KEY]?flags=[FLAGS]&url=[CAMERA_CONNECTION_URL]
  • [CAMERA_CONNECTION_URL] : An example of a connection url is as follows rtsp://CAMERA_CONNECTION_URL:554/. This url can vary with different camera brands and models.
  • [FLAGS] : You can put default to automatically put -v quiet -print_format json -show_format -show_streams.

Brute Protection Lock Reset

http://xxx.xxx.xxx.xxx/[API KEY]/resetBruteProtection/[GROUP KEY]

Monitor Triggers

Control - Point Tilt Zoom (PTZ)

[ACTION] is the action in which you want to run. See below for a list of available actions.
http://xxx.xxx.xxx.xxx/[API KEY]/control/[GROUP KEY]/[MONITOR ID]/[ACTION]
  • center
  • up
  • down
  • left
  • right
  • enable_nv
  • disable_nv
  • zoom_in
  • zoom_out

Trigger a Motion Event

This is a way to trigger the Motion Engine through a GET request.
http://xxx.xxx.xxx.xxx/[API KEY]/motion/[GROUP KEY]/[MONITOR ID]?data={"plug":"camera1","name":"stairs","reason":"motion","confidence":197.4755859375}
  • plug : The name of the plugin. You can put the name of the camera.
  • name : The name of the region. Example : door
  • reason : The reason for this trigger. Example : motion
  • confidence : A number to signify how much confidence this engine has that there is motion. Example : 197.4755859375

Webhook Test on monitor

Use this to help you test webhook usability of an external script.
http://xxx.xxx.xxx.xxx/[API KEY]/hookTester/[GROUP KEY]/[MONITOR ID]

Set to a mode for a monitor.

http://xxx.xxx.xxx.xxx/[API KEY]/monitor/[GROUP KEY]/[MONITOR ID]/[MODE]

[MODE] can be one of the following.

  • stop, start, record
  • stop = Disabled
  • start = Watch-Only
  • record = Record

Set to a mode for a number of minutes to elapse before automatically stops.

http://xxx.xxx.xxx.xxx/[API KEY]/monitor/[GROUP KEY]/[MONITOR ID]/[MODE]/[TIME]

Set to a mode for a period of time before automatically stops.

http://xxx.xxx.xxx.xxx/[API KEY]/monitor/[GROUP KEY]/[MONITOR ID]/[MODE]/[TIME]/[TIME INTERVAL]

Here is an example of setting the mode to record on a camera with ID bunny under group key 2Df5hBE. It will stay in this mode until changed.

http://xxx.xxx.xxx.xxx/XXXXXXXXXXXXXXXXX/monitor/2Df5hBE/bunny/record

Setting the mode to record on a camera with ID bunny for 10 minutes under group key 2Df5hBE. It will automatically return to Disabled itself after 10 minutes.

http://xxx.xxx.xxx.xxx/XXXXXXXXXXXXXXXXX/monitor/2Df5hBE/bunny/record/10/min

[TIME INTERVAL] can be left blank to use seconds or one of the following.

min, minute, minutes, hr, hour, hours, day, or days

Monitor States (Preset Configurations)

Monitor States are Presets that allow you to modify multiple monitors at once. This functionality is similar to ZoneMinder's "Alarm States".

Getting All Saved Monitor States

http://xxx.xxx.xxx.xxx/[API KEY]/monitorStates/[GROUP KEY]

Insert a Monitor States Preset

Only the values that you provide are changed. You can export your Monitor to get a list of possible choices.

The data query string needs to contain the monitors array. In this array you can place any set of configurations to change for your monitors.

http://xxx.xxx.xxx.xxx/[API KEY]/monitorStates/[GROUP KEY]/[PRESET_NAME]/insert?data={"monitors":[]}

Example of setting one monitor to Disabled and with the Detector Engine off.

http://xxx.xxx.xxx.xxx/[API KEY]/monitorStates/[GROUP KEY]/[PRESET_NAME]/insert?data={"monitors":[{"mid":"[MONITOR_ID_1]","mode":"stop","details":{"detector":"0"}}]}

Example of setting one monitor to Watch-Only and with the Detector Engine on.

http://xxx.xxx.xxx.xxx/[API KEY]/monitorStates/[GROUP KEY]/[PRESET_NAME]/insert?data={"monitors":[{"mid":"[MONITOR_ID_1]","mode":"start","details":{"detector":"1"}}]}

Delete Monitor States Preset

http://xxx.xxx.xxx.xxx/[API KEY]/monitorStates/[GROUP KEY]/[PRESET_NAME]/delete

Activate Monitor States Preset

http://xxx.xxx.xxx.xxx/[API KEY]/monitorStates/[GROUP KEY]/[PRESET_NAME]

Modifying a Video or Deleting it

Delete a video

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]/[FILENAME]/delete

Mark as Unread

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]/[FILENAME]/status/1

Mark as Read

http://xxx.xxx.xxx.xxx/[API KEY]/videos/[GROUP KEY]/[MONITOR ID]/[FILENAME]/status/2

Managing API Keys

Add an API Key

The created key is binded to the user who created it.
http://xxx.xxx.xxx.xxx/[API KEY]/api/[GROUP KEY]/add?data={}

Add an API Key : Sample of Post Data

The contents of details can vary based on version used.
{
   "data": {
      "ip": "[IP ADDRESS]",
      "details": {
         "auth_socket": "1",
         "get_monitors": "1",
         "control_monitors": "1",
         "get_logs": "1",
         "watch_stream": "1",
         "watch_snapshot": "1",
         "watch_videos": "1",
         "delete_videos": "1"
      }
   }
}

Delete an API Key

http://xxx.xxx.xxx.xxx/[API KEY]/api/[GROUP KEY]/delete?data={}

Delete an API Key : Sample of Post Data

{
   "data": {
      "code": "[API KEY]"
   }
}

Get API Keys

http://xxx.xxx.xxx.xxx/[API KEY]/api/[GROUP KEY]/list

Administrator Only

Register Sub-Account

A Sub-Account is an account that has limited privileges to the Administrator's Monitors, Videos, Events, and Logs.
http://xxx.xxx.xxx.xxx/admin/[API KEY]/accounts/[GROUP KEY]/register?data={}

Edit Sub-Account : Sample of Post Data

{
   "data": {
      "mail": "[SUB-ACCOUNT LOGIN ADDRESS]",
      "pass": "[SUB-ACCOUNT PASSWORD]",
      "password_again": "[SUB-ACCOUNT PASSWORD]"
   }
}

Edit Sub-Account

With this call you can modify permissions for the specified Sub-Account.
http://xxx.xxx.xxx.xxx/admin/[API KEY]/accounts/[GROUP KEY]/edit?uid=[USER ID]&mail=[LOGIN ADDRESS]&data={}

Edit Sub-Account : Sample of Post Data

The contents of details can vary based on version used.
{
   "uid": "[SUB-ACCOUNT USER ID]",
   "mail": "[SUB-ACCOUNT LOGIN ADDRESS]",
   "data": {
      "details": {
         "sub": "1",
         "allmonitors": "1"
      }
   }
}

Delete Sub-Account

With this call you can remove a Sub-Account and their associated API Keys.
http://xxx.xxx.xxx.xxx/admin/[API KEY]/accounts/[GROUP KEY]/delete?uid=[USER ID]&mail=[LOGIN ADDRESS]

Delete Sub-Account : Sample of Post Data

{
   "uid": "[SUB-ACCOUNT USER ID]",
   "mail": "[SUB-ACCOUNT LOGIN ADDRESS]"
}

Superuser Only

This user is the highest level user in the Shinobi system. It does not manage cameras, it manages Administrators and the system core.

Add an API Key for Superuser

Superusers must have their API Keys added explicity to the super.json file located in your Shinobi directory.

Example of added tokens variable to Superuser object in super.json

[
   {
      "mail": "[LOGIN ADDRESS]",
      "pass": "[PASSWORD]",
      "tokens": [
         "[A USER SPECIFIED API KEY]",
         "[ANOTHER USER SPECIFIED API KEY]",
         "[ANOTHER USER SPECIFIED API KEY]",
         "[ANOTHER USER SPECIFIED API KEY]"
      ]
   }
]

Update Superuser settings

Currently only for updating username and password. Leave the password fields blank to keep the current password and only change the username.
http://xxx.xxx.xxx.xxx/super/[API KEY]/accounts/saveSettings?data={"mail":"[LOGIN ADDRESS]","pass":"[NEW_PASSWORD]","pass_again":"[NEW_PASSWORD_AGAIN]"}

Update Superuser settings : Sample of Post Data

{
   "data": {
      "mail": "[LOGIN ADDRESS]",
      "pass": "[PASSWORD]",
      "pass_again": "[PASSWORD AGAIN]"
   }
}

Register Administrator

The only complex part of this registration method is filling the details column. See below for a Sample : Administrator object.
http://xxx.xxx.xxx.xxx/super/[API KEY]/accounts/registerAdmin?data={"mail":"[USERNAME]","pass":"[NEW_PASSWORD]","pass_again":"[NEW_PASSWORD_AGAIN]","ke":"[GROUP KEY]","uid":"[USER ID]","details":"[USER DETAILS]"}

Register Administrator : Sample of Post Data

The contents of details can vary based on version used.
{
   "data": {
      "mail": "[LOGIN ADDRESS]",
      "ke": "[GROUP KEY]",
      "pass": "[PASSWORD]",
      "password_again": "[PASSWORD AGAIN]",
      "details": {
         "factorAuth": "0",
         "size": "10000",
         "days": "5",
         "event_days": "10",
         "log_days": "10",
         "max_camera": "",
         "permissions": "all",
         "edit_size": "1",
         "edit_days": "1",
         "edit_event_days": "1",
         "edit_log_days": "1",
         "use_admin": "1",
         "use_aws_s3": "1",
         "use_webdav": "1",
         "use_discordbot": "1",
         "use_ldap": "1"
      }
   }
}

Edit Administrator

Tip : Post data does not have to be in a query string, it can be actual POST data as well.
http://xxx.xxx.xxx.xxx/super/[API KEY]/accounts/editAdmin?data={}&account={}

Edit Administrator : Sample of Post Data

The contents of details can vary based on version used.
{
   "data": {
      "mail": "[GROUP KEY]",
      "ke": "[GROUP KEY]",
      "pass": "[PASSWORD]",
      "password_again": "[PASSWORD AGAIN]",
      "details": {
         "factorAuth": "0",
         "size": "10000",
         "days": "5",
         "event_days": "10",
         "log_days": "10",
         "max_camera": "",
         "permissions": "all",
         "edit_size": "1",
         "edit_days": "1",
         "edit_event_days": "1",
         "edit_log_days": "1",
         "use_admin": "1",
         "use_aws_s3": "1",
         "use_webdav": "1",
         "use_discordbot": "1",
         "use_ldap": "1"
      }
   },
   "account": {
      "mail": "[GROUP KEY]",
      "ke": "[GROUP KEY]",
      "uid": "[USER ID]"
   }
}

Delete Administrator

Tip : Post data does not have to be in a query string, it can be actual POST data as well.
http://xxx.xxx.xxx.xxx/super/[API KEY]/accounts/deleteAdmin?account={}&deleteSubAccounts=1&deleteMonitors=1&deleteVideos=1&deleteEvents=1

Delete Administrator : Sample of Post Data

{
   "account": {
      "mail": "[LOGIN ADDRESS]",
      "ke": "[GROUP KEY]",
      "uid": "[USER ID]"
   },
   "deleteSubAccounts": "1",
   "deleteMonitors": "1",
   "deleteVideos": "1",
   "deleteEvents": "1"
}

Get all users registered to the database

This will not list Superusers.
http://xxx.xxx.xxx.xxx/super/[API KEY]/accounts/list

Get all users of a specific type

There are only two types to request. See below for choices.
http://xxx.xxx.xxx.xxx/super/[API KEY]/accounts/list/[TYPE]
  • admin
  • sub

Get system logs

http://xxx.xxx.xxx.xxx/super/[API KEY]/logs

Delete system logs

http://xxx.xxx.xxx.xxx/super/[API KEY]/logs/delete

Modify Configuration (conf.json)

[CONF.JSON] should be a JSON string of your conf.json file.
http://xxx.xxx.xxx.xxx/super/[API KEY]/system/configure?data=[CONF.JSON]

Update Shinobi

http://xxx.xxx.xxx.xxx/super/[API KEY]/system/update

Restart Shinobi

The [OPTIONS] parameter is to select which script to restart. Available uses are below.
http://xxx.xxx.xxx.xxx/super/[API KEY]/system/restart/[OPTIONS]
  • system
  • cron

Direct Camera Management via ONVIF

To get a full list of possible actions and options please refer to Futomi's ONVIF Documentiation.

Use a basic command

http://xxx.xxx.xxx.xxx/[API KEY]/onvif/[GROUP KEY]/[MONITOR ID]/[ACTION]

Use a service based command

http://xxx.xxx.xxx.xxx/[API KEY]/onvif/[GROUP KEY]/[MONITOR ID]/[SERVICE]/[ACTION]

Example of ptzMove. You can add options by adding the options query variable.

http://xxx.xxx.xxx.xxx/XXXXXXXXXXXXXXXXX/onvif/2Df5hBE/bunny/ptzMove?options={"speed":{"x":1,"y":0,"z":0},"timeout":1}

Example of device.getCapabilities

http://xxx.xxx.xxx.xxx/XXXXXXXXXXXXXXXXX/onvif/2Df5hBE/bunny/device/getCapabilities

Add, Edit or Delete a Monitor

Configuration of monitors remotely.

http://xxx.xxx.xxx.xxx/[API KEY]/configureMonitor/[GROUP KEY]/[MONITOR ID]/[ACTION*]?data={"mid":..}
  • [ACTION*] can be set to delete or not used entirely, There are no other options.
  • It is not necessary to put the data JSON if you are deleting.
  • The act of adding a monitor with an already existing ID will edit the existing monitor.
  • For an example of what to put for the data object check out this Sample JSON.

Embedding Streams

Embedding a websocket stream can be done through an iframe or using a GET request. You can even proxy it through another web engine because the embed URL will only start a stream after it gets the websocket library.

http://xxx.xxx.xxx.xxx/[API KEY]/embed/[GROUP KEY]/[MONITOR ID]

You can add jQuery with this method.

http://xxx.xxx.xxx.xxx/[API KEY]/embed/[GROUP KEY]/[MONITOR ID]/jquery

It's good for :

  • Direct access from a browser tab.
  • In an iframe
  • On a page without jQuery

You can embed with jQuery like this

$.get('http://xxx.xxx.xxx.xxx/[API KEY]/embed/[GROUP KEY]/[MONITOR ID]',function(data){ $('body').append(data) })

You can use it in an iframe like this

<iframe src="http://xxx.xxx.xxx.xxx/[API KEY]/embed/[GROUP KEY]/[MONITOR ID]/jquery|fullscreen"></iframe>

other available options are as follows. You must separate them with |

  • jquery : this addon adds jquery to the embed page. By default jquery is not loaded in case you have already loaded it where you are embedding the stream.
  • fullscreen : This adds CSS rules to fullscreen the stream element. This is good when embedding with an iframe.
  • gui : Extra CSS rules are added to display other information the Shinobi engine might have to provide.

You cannot use the URL like this

<img src="http://xxx.xxx.xxx.xxx/[API KEY]/embed/[GROUP KEY]/[MONITOR ID]">

Embedding on WordPress? You may need to set jQuery like this before the embed code for the feature to work.

$=jQuery

Support Shinobi development by subscribing to Shinobi Honor for the cost of two chocolate bars (USD).