API reference

Commands and parameters for the e3v-watchtower RESTful HTTP API.

The HTTP API for the cameras can be directly accessed using a variety of languages that support standard HTTP requests, with python and MATLAB example snippets being illustrated here.

You should have network access to the e3v-watchtower process running on the camera host computer (see Network layout for more setup details.)

Setting up for scripted API calls

Python-based API calls as shown below require the requests library or similar, usually available in a full python3 or anaconda install.

MATLAB-based API calls as shown below require the webread and webwrite functions implemented in MATLAB R2015b or later with suppport for ArrayFormat.

# import necessary libraries
import urllib3, requests, json

# set watchtower URL
watchtowerurl = 'https://localhost:4343'

# if Watchtower hosted on a remote system, with example IP 10.20.64.128
watchtowerurl = 'https://10.20.64.128:4343'
% set watchtower URL
watchtowerurl = 'https://localhost:4343';

% if Watchtower hosted on a remote system, with example IP here 10.20.64.128
watchtowerurl = 'https://10.20.64.128:4343';

Obtaining an API token

If you started Watchtower using Start Watchtower with web remote access, API calls must include an apitoken to authenticate yourself, obtained using a username and password pair set at initial setup.

If you are using Watchtower from local machine only (with watchtowerurl set to a localhost-based adddress, you do not need to obtain an API token.)

Parameters Value Description
username string Valid log-in username as registered at initialization (/firstuse), or any new users created at /register
password string Valid registered password string for above username 
# Obtain an API token, with example username "whitematter" and password "adminpass"
username = 'whitematter'
password = 'adminpass'
r = requests.post(watchtowerurl + '/api/login', data = \
    {'username': username, 'password': password}, verify=False)
j = json.loads(r.text)
apitoken = j['apitoken']
% Obtain an API token, with example username "whitematter" and password "adminpass"
username = 'whitematter';
password = 'adminpass';
loginresponse = webwrite([watchtowerurl, '/api/login'], ...
    'username', username, 'password', password, ...
    weboptions('CertificateFilename',''));
apitoken = loginresponse.apitoken;

Connecting/Disconnecting cameras

Binding cameras

Operational camera commands, such as CONNECT or DISCONNECT, must be issued in a cryptographically secure session between the Watchtower software and the cameras. This session is started by "binding".

Parameters Value Description
Id numeric integer Corresponds to database entry, can be looked up using the camera listing. Either Id or Serial must be set.
Serial string Camera unit serial as a string, such as e3v8100 or e3v8100.local. Either Id or Serial must be set.
Action BIND Must be set to the literal string BIND 
# standby cameras e3v8100 through e3v8103:
for camserial in ['e3v8100', 'e3v8101', 'e3v8102', 'e3v8103']:
    requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'Serial': camserial, 'Action': 'BIND'}, verify=False)
for cam_i = 1:4
response = webwrite([watchtowerurl, '/api/cameras/action'],...
        'Id', camera_ids[cam-i], Action', 'BIND', ...
        weboptions('CertificateFilename',''));
end

Connect to camera stream

This is the main command used for starting up cameras.

Parameters Value Description
Id numeric integer Corresponds to database entry, can be looked up using the camera listing. Either Id or Serial must be set.
Serial string Camera unit serial as a string, such as e3v8100 or e3v8100.local. Either Id or Serial must be set.
Action CONNECT Must be set to the literal string CONNECT
Iface ip address IP address of the listening interface where video is to be streamed, such as 10.20.64.128. Set to empty string for automatic interface detection.
Config 480p15
480p30
600p15
600p30
600p60
720p15
720p30
1200p10
1200p15
1200p30

Video recording resolution and framerate.

For example, 480p15 refers to 640x480 @ 15 frames/sec; 720p30 refers to 1280x720 @ 30 frames/sec.

480p: 640×480 resolution
600p: 800×600 resolution
720p: 1280×720 resolution
1600p: 1600×1200 resolution
Codec H264
MJPEG		 Video codec:

H264: produces .mp4 files. This is the most efficient form of video storage in Watchtower and suited for long-term recordings (~5x smaller file sizes than MJPEG). However, the video stream will have a buffering delay of 1-2 seconds and are not suitable for real-time image processing or triggering.

MJPEG: produces .avi files; bigger than H264-encoded .mp4s. They are near-real-time (2 frames of buffer delay, or as low as 33 ms) and are suitable for real-time image processing, such as real-time DeepLabCut.
Annotation Name
Time
Name+Time
None		 None: Do not overlay any text.
Time: Overlay time obtained over the network.
CameraName: Overlay the camera name (from step 10).
Name+Time: Overlay both time and camera name.
Segtime string with h m s Automatic rollover of video segment with a duration string, such as 15m, 1h30m, 45m30s
apitoken string (optional) if needed, API token as obtained above 
# start camera Id 1 through 4:
for camid in range(4):
    requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'Id': camid, 'Action': 'CONNECT', 'Iface': interface, 'Config': resolution, \
    'Codec': codec, 'Annotation': anno, 'Segtime': segment}, verify=False)

# start camera Serial e3v8100 through e3v8103:
for camserial in ['e3v8100', 'e3v8101', 'e3v8102', 'e3v8103']:
    requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'Serial': camserial, 'Action': 'CONNECT', 'Iface': interface, 'Config': resolution, \
    'Codec': codec, 'Annotation': anno, 'Segtime': segment}, verify=False)
for cam_i = 1:4
response = webwrite([watchtowerurl, '/api/cameras/action'],...
        'Id',camera_ids[cam-i],...
        'Action','CONNECT','Iface', interface, 'Config', resolution, ...
        'Codec', codec', 'Annotation', anno, 'Segtime', segment, ...
        weboptions('CertificateFilename',''));
end

Standby / disconnect cameras

Parameters Value Description
Id numeric integer Corresponds to database entry, can be looked up using the camera listing. Either Id or Serial must be set.
Serial string Camera unit serial as a string, such as e3v8100 or e3v8100.local. Either Id or Serial must be set.
Action DISCONNECT Must be set to the literal string DISCONNECT
apitoken string (optional) if needed, API token as obtained above 
# standby cameras e3v8100 through e3v8103:
for camserial in ['e3v8100', 'e3v8101', 'e3v8102', 'e3v8103']:
    requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'Serial': camserial, 'Action': 'DISCONNECT'}, verify=False)
for cam_i = 1:4
response = webwrite([watchtowerurl, '/api/cameras/action'],...
        'Id', camera_ids[cam-i], Action', 'DISCONNECT', ...
        weboptions('CertificateFilename',''));
end

Update sync source

Note that this must be set before Connecting cameras, if not yet set via the API or web interface.

Parameters Value Description
Id numeric integer Corresponds to database entry, can be looked up using the camera listing. Either Id or Serial must be set.
Serial string Camera unit serial as a string, such as e3v8100 or e3v8100.local. Either Id or Serial must be set.
Action UPDATEMC Must be set to the string UPDATEMC
apitoken string (optional) if needed, API token as obtained above 
# Updates the sync source to camera serial e3v8100
response = requests.post(watchtowerurl + '/api/cameras/action', data = \
    {'Serial': 'e3v8100', 'Action': 'UPDATEMC'}, verify=False)

# Updates the sync source to database Id 5.
response = requests.post(watchtowerurl + '/api/cameras/action', data = \
    {'Id': 5, 'Action': 'UPDATEMC'}, verify=False)
% Updates the sync source to camera serial e3v8100
response = webwrite('https://localhost:4343/api/cameras/action', ...
    'Serial': 'e3v8100', 'Action': 'UPDATEMC', ...
    weboptions('CertificateFilename',''));

response = webwrite('https://localhost:4343/api/cameras/action', ...
    'Id': 5, 'Action': 'UPDATEMC', ...
    weboptions('CertificateFilename',''));

Control camera recordings

Start saving

Creates a set of concurrent saved videos under the pre-set save path with the name [cameraname]-[starttime]-[endtime].[avi | mp4]. This is always a grouped operation.

Parameters Value Description
IdGroup[] numeric array Array corresponding to database entries, can be looked up using the camera listing. Either IdGroup[] or SerialGroup[] must be set.
SerialGroup[] string array Array of camera unit serials, such as [e3v8100, e3v8101]. Either IdGroup[] or SerialGroup[] must be set.
Action RECORDGROUP Must be set to the literal string RECORDGROUP
AdditionalPath string (optional) additional subdirectory to nest saved videos under; only applies to videos started this time and does not update global save path
apitoken string (optional) if needed, API token as obtained above 
# Start simultaneous video recordings of cameras e3v8100 through e3v8103:
response = requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'SerialGroup[]': ['e3v8100', 'e3v8101', 'e3v8102', 'e3v8103'], \
    'Action': 'RECORDGROUP'}, verify=False)

# Start simultaneous video recordings of camera Id 1 through 4:
response = requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'IdGroup[]': [1, 2, 3, 4], \
    'Action': 'RECORDGROUP'}, verify=False)
% Start simultaneous video recordings of cameras e3v8100 through e3v8103:
response = webwrite([watchtowerurl, '/api/cameras/action'], ...
        'SerialGroup[]', ["e3v8100", "e3v8101", "e3v8102", "e3v8103"], 'Action', 'RECORDGROUP', ...
        weboptions('CertificateFilename','','ArrayFormat','repeating'));

Stop saving

Parameters Value Description
IdGroup[] numeric array Array corresponding to database entries, can be looked up using the camera listing. Either IdGroup[] or SerialGroup[] must be set.
SerialGroup[] string array Array of camera unit serials, such as [e3v8100, e3v8101]. Either IdGroup[] or SerialGroup[] must be set.
Action STOPRECORDGROUP Must be set to the literal string STOPRECORDGROUP
apitoken string (optional) if needed, API token as obtained above 
# Stop simultaneous video recordings of cameras e3v8100 through e3v8103:
response = requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'SerialGroup[]': ['e3v8100', 'e3v8101', 'e3v8102', 'e3v8103'], \
    'Action': 'STOPRECORDGROUP'}, verify=False)

# Stop simultaneous video recordings of camera Id 1 through 4:
response = requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'IdGroup[]': [1, 2, 3, 4], \
    'Action': 'STOPRECORDGROUP'}, verify=False)
% Stop simultaneous video recordings of cameras e3v8100 through e3v8103:
response = webwrite([watchtowerurl, '/api/cameras/action'], ...
        'SerialGroup[]', ["e3v8100", "e3v8101", "e3v8102", "e3v8103"], 'Action', 'STOPRECORDGROUP', ...
        weboptions('CertificateFilename','','ArrayFormat','repeating'));

Trigger video segment

Creates a set of real-time video segments centered around the time of API call under [cameraname]-[centertime]-[framecount].avi.

This is always a grouped operation, and can only be used with cameras set to MJPEG.

Parameters Value Description
IdGroup[] numeric array Array corresponding to database entries, can be looked up using the camera listing. Either IdGroup[] or SerialGroup[] must be set.
SerialGroup[] string array Array of camera unit serials, such as [e3v8100, e3v8101]. Either IdGroup[] or SerialGroup[] must be set.
Action TRIGGERGROUP Must be set to the literal string TRIGGERGROUP
Duration string with s Must be 40s or shorter: for example: 30s creates a 30 second video segment, containing 15s before and 15s after the API call
AdditionalPath string (optional) additional subdirectory to nest saved videos under; only applies to videos started this time and does not update global save path
apitoken string (optional) if needed, API token as obtained above 
# Save simultaneous video triggered segments of cameras e3v8100 through e3v8103:
response = requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'SerialGroup[]': ['e3v8100', 'e3v8101', 'e3v8102', 'e3v8103'], \
    'Action': 'TRIGGERGROUP', 'Duration': '10s'}, verify=False)

# Save simultaneous video triggered segments of camera Id 1 through 4:
response = requests.post(watchtowerurl+'/api/cameras/action', data = \
    {'IdGroup[]': [1, 2, 3, 4], \
    'Action': 'TRIGGERGROUP', 'Duration': '10s'}, verify=False)
% Save simultaneous video triggered segments of cameras e3v8100 through e3v8103:
response = webwrite([watchtowerurl, '/api/cameras/action'], ...
        'SerialGroup[]', ["e3v8100", "e3v8101", "e3v8102", "e3v8103"], ...
        'Action', 'TRIGGERGROUP', 'Duration', '10s', ...
        weboptions('CertificateFilename','','ArrayFormat','repeating'));

Stream camera video

Raw camera live view can be streamed in H264 or MJPEG codecs, whichever was set at the time of connection.

Parameters Value Description
c string Camera unit serial as a string, such as e3v8100.
rate numeric (optional) Only applies to MJPEG streams: decimate video as a whole number fraction of the native framerate. For example, a 60 fps MJPEG camera can be streamed at 30, 10, 5, 2 fps, or any other whole number fraction

Example URL for streaming from a local e3vision, for camera serial e3v8100, viewed at 10 fps.

https://localhost:4343/api/stream/http?c=e3v8100&rate=10

Camera and file management

Scan for cameras

Parameters Value Description
apitoken string (optional) if needed, API token as obtained above 
response = requests.get(watchtowerurl+'/api/cameras/scan', verify=False)
response = webread([watchtowerurl, '/api/cameras/scan'], weboptions('CertificateFilename',''));

List cameras

Parameters Value Description
apitoken string (optional) if needed, API token as obtained above 
response = requests.get(watchtowerurl+'/api/cameras', verify=False)
response = webwrite([watchtowerurl, '/api/cameras'], weboptions('CertificateFilename',''));

Set global save path

This applies globally to all streaming cameras on next video file creation.

Parameters Value Description
Filepath string Global path where video files are saved
apitoken string (optional) if needed, API token as obtained above 
response = requests.post(watchtowerurl+'/api/sessions/rename', data = \
    {'Filepath': 'D:\Videos\Concurrent4AC3D'}, verify=False)
response = webwrite([watchtowerurl, '/api/sessions/rename'], ...
    'Filepath', 'D:\Videos\Concurrent4AC3D', weboptions('CertificateFilename',''));

Set global segment duration

This applies globally to all streaming cameras on next video file creation.

Parameters Value Description
Segment string with h m s Automatic rollover of video segment with a duration string, such as 15m, 1h30m, 45m30s
apitoken string (optional) if needed, API token as obtained above 
response = requests.post(watchtowerurl+'/api/sessions/segment', data = \
    {'Segment': '30m'}, verify=False)
response = webwrite([watchtowerurl, '/api/sessions/segment'], ...
    'Segment', '30m, weboptions('CertificateFilename',''));
Last modified August 18, 2020