You can control Agent using the local built-in server. Agent has a lot of commands you can call to integrate with other systems and home automation. Some commands take an object ID ( oid displayed at the top of the edit device tab) and a type ID (ot) 1 = microphone, 2 = camera. To use these just call the local server with the URLs provided. You can also pass in a group name to control multiple devices. Specify a group name on the devices under the General tab. There is an option in the server to setup Basic Authentication so your integration should support Basic Authentication if you are deploying it publicly.

New in v 3.8.1.0+ you can specify locations for commands as well. Assign a location to your devices and you can call commands like: command.cgi?cmd=record&location=upstairs

To add custom commands into the Agent DVR UI see Commands

There's also a python wrapper, agent-py available.

Our API examples and docs have moved to https://ispysoftware.github.io/Agent_API/

Some examples:

  • grab.jpg?oid=1&size=320x240 : return a still image of the camera resized to 320x240
  • grab.jpg?oids=1,2,3,4&size=640x320&maintainAR=true&backColor=255,0,0 : return a grid of 4 cameras resized to 640x320, maintaining aspect ratio for the images with a red background (RGB)
  • video.mjpg?oids=1,2,3&size=320x240 : return a grid of cameras in mjpeg form
  • video.mjpg?group=home&size=320x240&cycle=4 : return an mjpeg live feed of cameras in the group "home", cycling between them every 4 seconds (new in v3.4.7.0+)
  • video.mjpg?oids=1,2,3&size=640x480&maintainAR=true&backColor=0,255,0 : return a grid of cameras in mjpeg form with a green background.
  • video.mjpg?oids=1,2,3&size=640x480&fitType=Zoom&backColor=0,255,0 : return a grid of cameras in mjpeg form with a green background. Zoom into each camera to fit in its slot instead of resizing.
  • video.mp4?oids=1,2,3&size=320x240 : return a grid of cameras in mp4 form (the first camera with audio provides the audio stream). You can also use video.webm. See server settings/ streaming to set the framerate.
  • audio.mp3?oid=1 (or .ogg) : return live audio from the specified microphone
  • ptz.cgi?oid=1&dir=1 call PTZ on the camera. Specify dir = 0 for center, 1 = left, 2=up left, 3 = up, 4 = up right, 5 = right, 6 = down right, 7 = down, 8 = down left, 9 = zoom in, 10 = zoom out, 11 = stop. Pass in dur=1000 to auto send a stop command after 1 second (dur is in ms) (4.5.9.0+).<
  • ptz.cgi?oid=1&cmd=COMMAND : execute a command on the camera. COMMAND = the url encoded portion in the extended commands options from the PTZ2.xml file in Agent eg: ptz.cgi?oid=1&cmd=preset.cgi%3F-act%3Dgoto%26-number%3D0
  • ptz.cgi?oid=1&preset=Preset1 : go to a preset called Preset1 (4.5.9.0+)
  • command.cgi?oid=1&ot=2&cmd=alert : Trigger alert on the device. You can use any command (cmd) from: alert, detect, recordOnAlertOn, recordOnDetectOn, recordingOff, record, recordStop, alertOn/Off, switchOn/Off, ftpPhotosOn/Off, ftpRecordingsOn/Off, cloudPhotosOn/Off, cloudRecordingsOn/Off, saveLocalOn/Off, applyScheduleToDevice, scheduleOn/Off
  • command.cgi?oid=1&ot=2&cmd=recordStop&tag=something&useInactivity=true : Stop recording on the device, tag it with "something". Don't stop recording immediately - wait until the inactivity timeout expires (v4.5.9.0+).
  • command.cgi?oid=1&ot=2&cmd=snapshot Save a photo/ grab/ snapshot of the camera
  • command.cgi?group=upstairs&cmd=switchOff - apply the switch off command to all devices in the group upstairs. Specify the group on the device under "Groups" on the General tab.
  • command.cgi?cmd=arm : Arm Agent (enable alerting). You can also use: disArm, allOn, allOff, applySchedule, stopCloudUploads, rtmpStop
  • command.cgi?cmd=getObjects : return a JSON object describing the server and all devices
  • command.cgi?cmd=getObject&ot=2&oid=1 : return a JSON object describing the specified device
  • command.cgi?cmd=getStatus : return a JSON object with summary details for the server
  • command.cgi?cmd=ping : ping the server to check it is up. Responds with {"status":"OK"}
  • command.cgi?cmd=getProfiles : return a JSON object with available profiles for the server
  • command.cgi?cmd=reloadObjects : reload the objects.xml file from disk
  • command.cgi?cmd=reloadConfig : reload the config.xml file from disk
  • command.cgi?cmd=runstoragemgmt: trigger the storage management process to run - 4.1.1.0+
  • command.cgi?cmd=setdeepstackurl&oid=1&ot=2 : set the deepstack URL for the device (omit the device for the default deepstack setting) - 3.7.7.0+
  • command.cgi?cmd=record&ot=2&oid=1&tag=someone%20at%20the%20door : start recording and tag the recording with "someone at the door"
  • command.cgi?cmd=setProfile&ind=0 : apply the profile with an index of 0 (0=Home, 1=Away, 2=Night)
  • events.json?ot=1&oid=2&seconds=60 : return a JSON object with details of the device events over the last 60 seconds (seconds can be up to 600)
  • command.cgi?cmd=setobjectstate&ot=2&oid=1&state=Monitor : Set the working state of the device. Options are:
    • None - disabled
    • Monitor - enabled, no motion detection
    • Modect - enabled, record on detect (applies a simple detector if detector is None)
    • Redect - enabled, start recording, motion detection enabled (records until no motion is detected, applies a simple detector if detector is None)
    • Record - enabled, start recording, no motion detection (records until stopped)
  • q.json?cmd=queryLevel&ot=2&oid=1: Return the current motion/ sound level of the device with min 0, max 1.
New in v3.1.0.0
  • q.json?cmd=getevents or q.json?cmd=getevents&oid=4&ot=2 : return a list of recordings for all devices or a specific device.
    • If you receive 400 events you will need to make another call to getevents passing in enddate=x where x is the last received timestamp in the array to retrieve the next 400.
    • New in 3.9.6.0+ pass in tag=x to filter the results to recordings tagged with x
  • filethumb.jpg?oid=3&fn=3_2021-01-19_10-37-50_961.jpg : return a thumbnail of the recording. The filename is from the "fn" property in the json from the getevents call (with the extension replaced with .jpg).
  • filethumb.jpg?oid=3&fn=3_2021-01-19_10-37-50_961_large.jpg : return a full size image of the recording. The filename is from the "fn" property in the json from the getevents call (with the extension replaced with _large.jpg).
  • streamfile?oid=3&ot=2&fn=3_2021-01-21_16-34-42_977.mkv : stream the file to the caller. The filename is from the "fn" property in the json from the getevents call. It is up to the calling application to provide playback facility.
  • q.json?cmd=getcameragrabs&oid=3&ot=2 : return a list of photos for the specific device.
    • If you receive 800 grabs you will need to make another call to getcameragrabs passing in enddate=x where x is the last received timestamp in the array to retrieve the next 800.
  • grabthumb.jpg?oid=3&fn=2021-01-19_12-22-55_125.jpg : return a small (320x240) version of the of the photo. The filename is from the "fn" property in the json from the getcameragrabs call.
  • grabimage.jpg?oid=3&fn=2021-01-19_12-22-55_125.jpg : return a full size version of the of the photo. The filename is from the "fn" property in the json from the getcameragrabs call.
New in v3.2.3.0
  • q.json?cmd=addrecording&ot=2&oid=3&move=0&tags=blah&path=D:\test.mp4: add a recording to a device (useful for cameras that record themselves or cameras that can't be monitored by Agent). move parameter is 1 or 0 - 1 = delete original. Recording will be copied to the devices folder location within Agent.

New in v3.8.1.0: added name=outfilename, convert=true/false and timestamp=xxx options - this will use the filename you specify, convert the file to an mp4 before adding it and set the created date timestamp (in javascript ticks UTC)

New in v3.2.6.0
  • q.json?cmd=addcamera&substream=rtsp%3A%2F%2Fsomeurl.com%3A554%2Ffeed&mainstream=rtsp%3A%2F%2Fsomeurl.com%3A554%2Ffeed2&username=admin&password=123&alerts=1&record=1&resize=0&raw=1&fps=20&recfps=20&name=camera%20name: add a network camera called "camera name" with a live and a record url set, record on detect enabled and raw recording enabled. Stream and record at 20fps. All fields are optional.
New in v3.2.8.0
  • video.gif?oid=1&size=640x480&secs=10&framerate=5: Generate an animated gif from the live camera stream lasting 10 seconds running at 5fps.
New in v3.3.1.0
  • command.cgi?cmd=restart: Restart the Agent DVR application.
  • command.cgi?oid=3&ot=2&cmd=triggerlpr: Trigger License Plate Recognition (LPR). LPR must be enabled on the camera for this to work
New in v3.3.4.0
  • q.json?cmd=recordRestart&ot=2&oid=1: Stop recording (if it is recording) and start recording again.
New in v3.3.5.0
  • command.cgi?oid=3&ot=2&cmd=triggerface: Trigger Facial Recognition. Facial Recognition must be enabled on the camera for this to work
New in v3.3.8.0
  • command.cgi?oid=3&ot=2&cmd=triggerobject&labels=car,person&confidence=60&snapshot=true&norepeat=true&showlabels=true: Trigger DeepStack Object Recognition. This will search the current frame for objects and if any of them match it will fire a DeepStack Object Found event. If not found it will fire a DeepStack Object Not Found event. Pass in labels to look for from the deepstack label list (comma seperated if more than one) and optionally a minimum confidence (0 - 100, default is 60), a snapshot flag to control whether to save an image with the results from the deepstack call, showlabels to control whether to draw labels on top of the image (v3.8.1.0+) and norepeat to stop Agent finding the same object in the previous calls locations. Object Recognition must be enabled on the camera for this to work.
  • command.cgi?oid=3&ot=2&cmd=triggerobject: Trigger DeepStack Object Recognition with the configured settings on the camera's Object Recognition settings. Object Recognition must be enabled on the camera for this to work.
New in v3.4.2.0
  • q.json?cmd=settimestamp&oid=3&ot=2&text=FPS%3A%20%7BFPS%7D%20%7B0%3AG%7D%0AWeather%3A%20Sunny%0ATemp%3A%2022%C2%B0: Modify the timestamp on the camera (for example to pass in weather information). This must be URL encoded. If you use this be sure to pass in the URL encoded formatter for the timestamp itself, for example: text=FPS%3A%20%7BFPS%7D%20%7B0%3AG%7D%0A. See https://www.urlencoder.org/ to generate text.
  • q.json?cmd=appendtimestamp&oid=3&ot=2&text=Weather%3A%20Sunny%0ATemp%3A%2022°: This appends text to the configured timestamp on the camera (for example to pass in weather information).
New in v3.5.5.0
  • command.cgi?oid=3&ot=2&cmd=triggertask&task=Lights%20On: Trigger a task on a camera with ID 3 called "Lights On".
New in v3.5.9.0

We added a flag to configuration to block external access from the website. You can use this to lock down your server for extra safety or if you think your login has been compromised. You can turn this on or off via the local UI or automate it via the API:

  • command.cgi?cmd=blockexternal: Block external access from the website.
  • command.cgi?cmd=unblockexternal: Unblock external access from the website.
New in v3.6.7.0
  • command.cgi?oid=3&ot=2&cmd=ftpframe: Send a live frame via FTP
New in v3.7.5.0
  • command.cgi?oid=3&ot=2&cmd=seturi&live=http%3A%2F%2Fsomeurl.com%2Fvideo.asf%3Ffeed%3D1&record=http%3A%2F%2Fsomeurl.com%2Fvideo.asf%3Ffeed%3D2: Modify the live and record uri's for a camera. You can provide live and/or record. The camera will restart.

New in 3.7.7.0

  • alerts.json: Return JSON object for current alerts
New in v3.7.9.0
  • q.json?cmd=addonvif&substream=0&mainstream=1&username=admin&password=password&alerts=1&record=1&resize=0&raw=1&fps=20&name=camera%20name&uri=http://192.168.0.1/onvif/device_service: add an onvif camera using the discovery endpoint http://192.168.0.1/onvif/device_service. Use stream index 0 for the live stream and 1 for record stream. Called "camera name" with a live and a record url set, record on detect enabled and raw recording enabled. All fields are optional apart from discovery URI.
New in v3.8.7.0
  • q.json?cmd=getsessioncount: get the number of connected viewing clients.
Url options

You can open Agent to a specific view by calling the Agent url with (case sensitive):

  • ?start=Live&viewIndex=3 (live view on view 3)
  • ?start=TimeMachine (timemachine view)
  • ?start=TimeLine (timeline view)
  • ?start=Photos (photos view)
  • ?start=Recordings (recordings view)
  • ?start=Floorplans&planIndex=2 (floorplans view on plan 2)
  • ?start=VR (virtual reality)

You can open Agent with a specific language (bypassing the language selection). Just pass in the 2 letter language code: ?lang=fr

New in v3.9.0.0

You can now arm or disarm Agent and groups of devices. Pass 0 into the delay fields to disable delay functions. Pass -1 into the ind field to use the current profile/ configuration.

  • q.json?cmd=armprofile&ind=0&disarmdelay=2: Arm agent, apply profile 0 (0 = Home, 1 = Away, 2 = Night, 3 = Disabled). Disarm in 2 minutes.
  • q.json?cmd=disarmprofile&ind=1&armdelay=5: Disarm agent, apply profile 1 (0 = Home, 1 = Away, 2 = Night, 3 = Disabled). Re-arm in 5 minutes.
  • q.json?cmd=armgroups&groups=upstairs,outside&disarmdelay=5: Enable alerts on all devices with the group upstairs or outside. Disarm the same devices after 5 minutes. (will also arm agent if it isn't armed already)
  • q.json?cmd=disarmgroups&groups=upstairs,outside&armdelay=5: Disable alerts on all devices with the group upstairs or outside. Re-arm the same devices after 5 minutes. (Re-arming will also arm agent if it isn't armed already)
New in v4.0.0.1

Set max, min and gain values for motion/ sound detection (v4.0.0.1+):

  • q.json?cmd=setsensitivity&ot=2&oid=1&min=10&max=80&gain=1.5: set the minimum sensitivity to 10%, maximum to 80% and the gain to 1.5. Note that max and min are percentages (0 - 100) and Gain is a positive decmial number between 0.0001 and 99999999. All parameters are optional and if not specified will be unchanged.
New in v4.1.0.0

You can pass in the name of a saved filter to apply using a filter parameter - eg: ?start=Recordings&filter=intruder. You can also pass in a from and to time for the filter using javascript ticks. eg ?start=timeline&from=1657841514949&to=1657852514949.

Set default theme options (theme options are available in the account menu - theme settings):

  • ?theme=darkly&variant=dark&large=false
  • ?theme=sketchy&variant=primary&large=true

Auto play audio on load (v3.7.7.0+ may also require changing browser settings):

  • ?playaudio=true

Start in minimised mode (top and bottom UI bars hidden) (v3.8.7.0+):

  • ?mini=true

Pass in local username and password for auto login (v4.7.6.0+) (caution - this will expose your credentials to the network):

  • ?un=username&pwd=password
RTMP Push control (4.2.7.0+)

RTMP servers are configured in server settings. You can stop and start RTMP push manually via the server menu - RTMP Streaming

  • q.json?cmd=getstreamingstatus : get a JSON list of configured RTMP servers (with status). This provides an {IDENT} field you use in subsequent requests.
  • q.json?cmd=start-rtmp&ident={IDENT}&ot=2&oid=20 : Start RTMP push to the server with camera ID 20
  • q.json?cmd=start-rtmp-view&ident={IDENT}&ind=0 : Start RTMP push to the server with the first live view (views are numbered 0-8)
  • q.json?cmd=stop-rtmp&ident={IDENT} : Stop RTMP push to a specific server
  • q.json?cmd=stop-rtmp&ident=all : Stop RTMP push to all servers
New in v4.3.4.0

Switch the detector on or off

  • q.json?cmd=switchdetector&ot=2&oid=1&on=true Enable the detector on the device
  • q.json?cmd=switchdetector&ot=2&oid=1&on=false Disable the detector on the device
New in v4.5.5.0

Enable, disable and run actions

  • command.cgi?cmd=actionOn&id=[ID] Enable the action
  • command.cgi?cmd=actionOff&id=[ID] Disable the action
  • command.cgi?cmd=actionRun&id=[ID] Run (execute) the action

[ID] is the ID of the action (displayed at the top of the control when editing the action in the UI)

Authentication

By default Agent runs the local server without authentication (as remote access is secured behind our SSL hosted login page). You can enable Basic Authentication in Server Settings - Users tab by adding a user and check Protect API on the Local Server tab. Your integration should detect an authentication challenge response from the server and prompt for credentials if needed.