Skip to main content

Cameras and edge nodes

See Cameras and edge nodes for how cameras, edge nodes and assignment work.

Reading endpoints work for operators and admins. Endpoints that change cameras need the admin role.

The camera object​

idintegeroptional
The camera ID.
namestringoptional
The camera name. Unique.
source_uristringoptional
The stream URL. Admins get it in full, including any credentials written into it. For operators, credentials are replaced with ***.
organization_idintegeroptional
The organization the camera belongs to.
organization_namestringoptional
The organization's name.
detection_profilestringoptional
The key of the camera's detection profile.
zone_configobjectoptional
A read-only copy of the camera's zones, as {"zone name": polygon}.
enabledbooleanoptional
Whether the camera is processed.
assigned_node_idinteger or nulloptional
The edge node that processes it, or null if unassigned.
last_frame_atstring or nulloptional
When the edge node last read a frame from the camera.
live_urlstring or nulloptional
The address of the camera's live view, with a short-lived signed token. Use it as an image source in a signed-in browser session. null when the camera is unassigned or its edge node is offline. Tokens last 5 minutes; list the cameras again for a fresh one.
created_atstringoptional
When the camera was added.

List cameras​

GET/cameras

Lists every camera, in the order they were added.

Query parameters​

organization_idintegeroptional
Only cameras in this organization.

Responses​

200
An array of cameras.
401
You are not signed in.

Add a camera​

POST/cameras

Adds a camera. If you assign it to an edge node, that node starts processing it within about 10 seconds. Requires the admin role.

Body​

namestringrequired
The camera name. Must be unique within the organization.
source_uristringrequired
The stream URL, for example rtsp://192.168.1.100:554/stream.
organization_idintegerrequired
The organization. Every site has a Default Organization; get its ID from GET /organizations.
detection_profilestringoptional
The key of a detection profile. Always send it. If the key doesn't match a profile, the camera uses the default profile.
assigned_node_idinteger or nulloptional
The edge node to process it. Leave it out or send null to save the camera unassigned.

Responses​

201
The camera was added. Returns the camera.
403
You are not an admin.
409
A camera with this name already exists in the organization.
422
A field is missing, or no organization has this ID.

Change a camera​

PATCH/cameras/{camera_id}

Changes one or more fields. Send only the fields you want to change. Requires the admin role.

Path parameters​

camera_idintegerrequired
The camera.

Body​

namestringoptional
A new name. Rules that filter by the old name stop matching it.
source_uristringoptional
A new stream URL. The edge node restarts the camera with it.
organization_idintegeroptional
Move the camera to another organization.
detection_profilestringoptional
The key of another detection profile.
enabledbooleanoptional
false stops processing and keeps the camera's history.

Responses​

200
The camera was changed. Returns the camera.
403
You are not an admin.
404
No camera with this ID, or the body has no fields.
409
Another camera in the organization has this name.
422
No organization has this ID.

Assign a camera to an edge node​

PATCH/cameras/{camera_id}/assign

Moves a camera to an edge node, or unassigns it. Requires the admin role.

Path parameters​

camera_idintegerrequired
The camera.

Body​

assigned_node_idinteger or nullrequired
The edge node ID from GET /edge-nodes, or null to unassign the camera.

Responses​

200
The assignment changed. Returns the camera.
403
You are not an admin.
404
No camera with this ID.
422
No edge node with this ID.

Delete a camera​

DELETE/cameras/{camera_id}

Deletes a camera that has no history, and its zones. A camera with detections or events can't be deleted. Disable it instead. Requires the admin role.

Path parameters​

camera_idintegerrequired
The camera.

Responses​

200
The camera was deleted. The body is {"status": "deleted"}.
403
You are not an admin.
404
No camera with this ID.
409
The camera has events or tracks.

Test a stream​

POST/cameras/test-connection

Opens a stream, reads one frame and returns it as a JPEG data URL. Use it to check a URL and its credentials before you save a camera. The site node opens the stream, so it must be able to reach the camera. Requires the admin role.

Accepted sources are rtsp://, rtsps://, http:// and https:// URLs. Addresses on the site node itself (loopback), link-local addresses and cloud metadata addresses are refused. Private network addresses, where cameras usually live, are allowed.

Body​

source_uristringrequired
The stream URL to test.

Response fields​

snapshotstringoptional
The frame, as a data:image/jpeg;base64,... URL.

Responses​

200
The stream works.
403
You are not an admin.
422
The URL is not allowed, the stream couldn't be opened, or no frame could be read. Error messages never repeat the camera's credentials.

Get a snapshot​

GET/cameras/{camera_id}/snapshot

Returns the current frame of a saved camera as a JPEG image. Useful as a background when you draw a zone.

Path parameters​

camera_idintegerrequired
The camera.

Responses​

200
A JPEG image.
404
No camera with this ID.
502
The stream couldn't be opened or read.

Stream a camera​

GET/cameras/{camera_id}/stream

Streams a saved camera as MJPEG (multipart/x-mixed-replace), at up to 10 frames a second, through the site node. The dashboard's single-camera view uses it. Each open stream makes the site node open its own connection to the camera. The Live Wall uses each camera's live_url instead, which is served by the edge node.

Path parameters​

camera_idintegerrequired
The camera.

Responses​

200
An MJPEG stream. If the camera can't be read, the stream ends.
401
You are not signed in.
404
No camera with this ID.
502
The stream couldn't be opened.

Zones​

A zone is a named area of a camera's picture, such as "Loading dock". Workflow conditions refer to a zone by its name. See Zones.

Polygon points are [x, y] pairs given as fractions of the picture's width and height, from 0 to 1. [0, 0] is the top-left corner and [1, 1] the bottom-right, so zones stay correct if the camera's resolution changes.

Listing zones works for operators and admins. Adding and deleting zones needs the admin role. Zone changes reach the rule engine within about 10 seconds.

GET/cameras/{camera_id}/zones

Lists a camera's zones, each with id, camera_id, name, polygon and created_at.

POST/cameras/{camera_id}/zones

Adds a zone to a camera.

Body​

namestringrequired
The zone name. Unique per camera.
polygonarrayrequired
At least 3 [x, y] points, each coordinate from 0 to 1.
DELETE/zones/{zone_id}

Deletes a zone. Workflows that name it stop matching on that camera.

Responses​

200
Done. A new zone is returned with its id.
403
You are not an admin.
404
No camera or zone with this ID.
409
The camera already has a zone with this name.
422
The name is empty, or the polygon has fewer than 3 points or a coordinate outside 0 to 1.

Organizations​

Organizations group cameras, for example by building or tenant. Every site starts with one, Default Organization. Listing works for operators and admins; the other endpoints need the admin role.

GET/organizations

Lists organizations with id, name, description, camera_count, created_at and updated_at. GET /organizations/{org_id} returns one.

POST/organizations

Adds an organization. Body: name (required, unique) and description.

PATCH/organizations/{org_id}

Changes name or description.

DELETE/organizations/{org_id}

Deletes an organization that has no cameras. Move or delete its cameras first.

Responses​

200
Done. POST returns 201 with the organization.
403
You are not an admin.
404
No organization with this ID.
409
The name is taken, or the organization still has cameras.

List edge nodes​

GET/edge-nodes

Lists the edge nodes that have registered with the site, sorted by name. Each running edge node refreshes last_heartbeat about every 10 seconds. The dashboard shows a node as online when its last heartbeat is less than 30 seconds old.

Response fields​

An array of edge nodes:

idintegeroptional
The edge node ID.
namestringoptional
The node name.
last_heartbeatstringoptional
When the node last checked in.
public_hoststring or nulloptional
The address browsers use for the node's live view. By default the path /edge/<node name> on the dashboard's own HTTPS address.
public_host_overriddenbooleanoptional
true when an admin has pinned public_host.

Responses​

200
The edge nodes.
401
You are not signed in.

Set an edge node's live view address​

PATCH/edge-nodes/{node_id}

Pins the address browsers use for this node's live view. A pinned address is kept until you clear it; the node's own setting no longer overwrites it. Requires the admin role.

Use a same-origin path such as /edge/edge-2 where you can. An http:// address is blocked by browsers as mixed content on the HTTPS dashboard.

Path parameters​

node_idintegerrequired
The edge node.

Body​

public_hoststring or nullrequired
The address, or null to clear the pin. The node then registers its own address again on its next heartbeat.

Responses​

200
The node, as in the list.
403
You are not an admin.
404
No edge node with this ID.
422
public_host is missing or not a valid address.
Was this page helpful?