CCTV

A facility's CCTV cameras and edge processors, and the camera catalogue. list shows AI edge processors with the network (RTSP/HTTP) cameras each one records, and cloud cameras; get shows one; status says which are online; snapshot returns a camera's latest still; capabilities shows a camera's image settings and motion mask. catalog_search and catalog_templates look up stream paths in the public camera database (the same data as "Find my camera" in Device Management). test_stream asks an edge processor to probe a stream before you add it. Stream credentials show as : unless includeCredentials is set; workflow steps and Agent devices never get stream addresses or IP addresses. Live video is never available here. To add, change, restart or remove cameras use cctv_cameras_write; for edge processors use cctv_edge_processors_write.

Actions:

• list: List cameras and edge processors. Edge processors (online means a heartbeat in the last 5 minutes, provisioning, system updates) with their cameras nested (stream status, offlineReason, IP, codec, recording and AI settings), then cloud cameras. Use it to pick an online edge processor or find a camera deviceUuid.
• get: Get a camera or edge processor. One camera or edge processor as list shows it, with its status (online, offline, pending or provisioning), why it's offline, when it was last seen, and a link to its recordings. Needs deviceUuid.
• status: Check which cameras are online. Every camera and edge processor with its status: online, offline (reason edge_processor_offline, not_streaming or no_heartbeat), pending (just added) or provisioning, plus counts and a one-line summary for messages. Narrow it with cameraIds or location; offlineOnly lists only what is offline (counts still cover everything chosen). A network camera is offline while its edge processor is.
• snapshot: Get a camera's latest still. The camera's latest still as an image, with capturedAt, a frameId and an imageUrl that shows its latest timelapse frame for 24 hours. Listed in Recent Access with who took it. Workflow steps and Agent devices need 'Workflows can share footage and identify people' turned on. Needs cameraId.
• capabilities: A camera's image settings and motion mask. A cloud camera reports its image settings (brightness, contrast and the like) live, within about 10 seconds; network cameras take theirs from the camera itself, so imageSettings is null. motionMask lists the areas where motion is ignored, as polygons with x and y from 0 to 1. Change them with cctv_cameras_write save_capabilities and save_mask. Needs deviceUuid.
• catalog_search: Search the camera catalogue. Find a manufacturer, series or model by the name or model number on the camera label, e.g. "CAM-0001". Each match has a manufacturer slug for catalog_templates and sometimes a templateId. Needs query.
• catalog_templates: A manufacturer's stream templates. Default port and username, stream templates and models. Prefer the template matching the search hit templateId, else the isDefault one. Templates look like rtsp://{username}:{password}@{ip}:{port}/Streaming/Channels/{channel}01; pass them as stream parts (mainStreamProtocol, camera IP, port, mainStreamPath with {channel} filled in, usually 1) so credentials are encoded server-side. Needs manufacturer.
• test_stream: Test a camera stream. The edge processor pings the camera, checks the port and probes the stream, then returns the outcome, codec, resolution, fps, logs and a snapshot image. Takes up to about 35 seconds. Run it for each camera before adding it; on failure the logs show the cause (wrong path or credentials, closed port, unreachable IP). Needs edgeProcessorUUID.

Changes the cameras at a facility. add puts network (RTSP/HTTP) IP cameras on an AI edge processor, which then pulls each stream for recording and AI (people tracking, motion). update changes a network or cloud camera. restart restarts a camera or edge processor that stopped responding. save_capabilities and save_mask change a camera's image settings and motion mask. remove takes a camera off the facility; its recordings stay until the retention period ends. Find cameras and edge processors with cctv_cameras_read list, and test each stream with cctv_cameras_read test_stream before adding it.

Actions:

• add: Add network cameras. Up to 25 per call. Each camera needs deviceName, cameraGroup (its location) and streamUrl or stream parts. Defaults: motion recording, people tracking on, 6 fps AI. All of the edge processor's streams reload once. Needs edgeProcessorUUID, cameras. Asks for confirmation.
• update: Change a camera. Only the settings you pass change. Network cameras also take peopleTracking, aiFramerate, transcription, a new stream (streamUrl or stream) and edgeProcessorUUID (move to another online edge processor); a new stream or edge processor asks for confirmation. Cloud cameras also take resolution. Needs deviceUuid. May ask for confirmation.
• remove: Remove a camera. A network camera is taken off its edge processor, whose other streams reload once. A cloud camera is decommissioned: unpaired so the hardware can be paired elsewhere. To replace an edge processor and keep its cameras, use cctv_edge_processors_write transfer_cameras. Needs deviceUuid. Asks for confirmation.
• restart: Restart a camera or edge processor. For a camera or edge processor that stopped responding. A cloud camera reboots. For a network camera, the edge processor that records it restarts, with all its cameras. An offline device may not get the restart (wasOnline); check cctv_cameras_read status a few minutes later. A workflow step restarts once per run. Needs deviceUuid. Asks for confirmation.
• save_capabilities: Change a camera's image settings. Cloud cameras only: send the settings to change as { : }, using the ids and allowed values from cctv_cameras_read capabilities. The camera's recorder restarts to apply them, so a few seconds aren't recorded. Needs deviceUuid, settings. Asks for confirmation.
• save_mask: Change a camera's motion mask. Replaces the areas where the camera ignores motion (an empty list clears them). Motion there no longer starts a recording or a 'Motion recorded' workflow. Read the current mask with cctv_cameras_read capabilities. Needs deviceUuid, polygons. Asks for confirmation.

Manages AI edge processors, the on-site devices that record network cameras and run their AI. Find their deviceUuid with cctv_cameras_read list, and check whether they are online with cctv_cameras_read status. To restart one use cctv_cameras_write restart; to move one (with its cameras) to another facility use device_inventory_write move.

Actions:

• pair: Pair a new edge processor. Adds an edge processor to the facility by the serial number on its label. It must be powered and online. Needs deviceSerialNumber.
• update: Rename or relocate an edge processor. Needs deviceUuid.
• transfer_cameras: Move all cameras to another edge processor. Moves every network camera from deviceUuid to another online edge processor at the facility (toUUID), e.g. when replacing failed hardware. Needs deviceUuid, toUUID. Asks for confirmation.
• decommission: Decommission an edge processor. Unpairs it so the facility can be deleted or the hardware reused. Refused while it still has cameras unless removeCameras is true. Needs deviceUuid. Asks for confirmation.

A facility's CCTV recordings: list and get them, see when each camera recorded (timeline), count them (summary), and look at a frame from one. Recordings are referred to by recordingId (from list, a CCTV trigger or cctv_search_anything); times are ISO 8601. Each recording has a link that opens it in the CCTV app. Videos themselves never leave the app; frame returns a still instead. To keep, release or label recordings use cctv_recordings_write.

Actions:

• list: List recordings. Newest first, with camera, start and end, status (uploading, available, keeping, kept), who kept it and its note. Narrow by from and to, cameraIds, location or kept; page with cursor.
• get: Get a recording. Needs recordingId.
• timeline: When cameras recorded. Per camera between from and to (at most 7 days): the time ranges it recorded, how many recordings and how many are kept. Use it to find gaps or busy periods. Needs from.
• summary: Count recordings. How many recordings the facility has (available, kept, uploading) and the oldest and newest, as the Recordings page counts them (updated hourly).
• filters: What recordings can be filtered by. The cameras and locations that have recordings, and the statuses list takes.
• frame: Look at a frame. A still from a recording nearest at (default its middle; within a minute, from the camera's timelapse), or a frame by frameId. Returns the image, its frameId and an imageUrl that shows it for 24 hours. Listed in Recent Access with who looked. Workflow steps and Agent devices need 'Workflows can share footage and identify people' turned on.

Keeps CCTV recordings so the facility's recording retention never deletes them, changes their note or name, and releases them again. Keeping records who kept it (a person, the AI Agent or the workflow by name) and is listed in Recent Access. Find recordings with cctv_recordings_read list, a CCTV trigger or cctv_search_anything. Workflow steps keep and label recordings once per run; only a person can release one.

Actions:

• keep: Keep recordings. Up to 50 recordings by recordingId, with an optional note. Each one reports kept, already_kept, not_uploaded (still uploading; try again later) or failed. Needs recordingIds.
• keep_range: Keep every recording in a time range. Keeps every recording that overlaps from to to (at most 24 hours) on cameraIds, or on every camera when none are given. Use it for an incident: a few minutes either side of when it happened. Needs from.
• update: Change a recording's note or name. Pass note, name or both; null or an empty string clears one. Needs recordingId.
• release: Release a kept recording. Undoes keep: the recording is deleted when the facility's recording retention ends, like any other. Only a person can release one, from AI chat or the CCTV app. Needs recordingId. May ask for confirmation.

Searches a facility's indexed CCTV media (person crops, recording frames and timelapse frames) by meaning, as the CCTV page does. Returns one list of hits, newest first.

Ask in any of four ways; text with an image or seed narrows (the words filter, the picture ranks):

• Text: query (e.g. "person in a red jacket near reception this morning") plus timezone. Time, zone and camera phrases become filters (smartQuery).
• Image: imageBase64 and imageMimeType.
• More like an earlier hit: copy its results[N].seed into seedIndex, seedRef and seedFrameId (or seedOffsetMs).
• Filters: from and to (epoch ms), zoneIds, cameraNames or cameraIds.

Scores order hits. They aren't percentages, and text and image scores can't be compared. perIndex.*.textGated explains an empty list ("matched the picture, not the words"). With an image or a person seed, matching people come first, in faceMatches (insights_people_read get).

Each hit has a seed, a 1-based resultIndex and captureTimeMs. Recording hits carry a recordingId (cctv_recordings_read get), timelapse hits a frameId (cctv_recordings_read frame). Nothing is searchable until an edge processor has built the facility's indexes.

How long the facility keeps recordings, timelapse frames and analysis, whether enhanced analysis is on, recording counts, the Live Views everyone at the facility shares, and whether "Workflows can share footage and identify people" is on. To change them use cctv_settings_write.

Actions:

• settings: Read the CCTV settings. recordingRetentionDays, timelapseRetentionMonths and analysisRetentionMonths ("all" means kept forever), enhancedAnalysis, and workflowControl.
• storage: Recording counts and retention. How many recordings the facility has (available, kept, still uploading), the oldest and newest, and how long each kind of footage is kept.
• live_views: List shared Live Views. The camera walls everyone at the facility shares, each with its cameras by id and name. A Live View can be shown on a display screen.
• workflow_control: Can workflows share footage and identify people?. Whether "Workflows can share footage and identify people" is on, and what it allows workflow steps and Agent devices to do.

Changes how long the facility keeps recordings, timelapse frames and analysis, turns enhanced analysis on or off, makes, changes and deletes the Live Views everyone at the facility shares, and turns "Workflows can share footage and identify people" on or off. Every change asks for confirmation except saving a Live View. Read the current values with cctv_settings_read. Workflow steps and Agent devices can't change CCTV settings.

Actions:

• save_settings: Change CCTV settings. Pass only the settings to change. Shortening a retention deletes older footage (kept recordings stay). May ask for confirmation.
• save_live_view: Make or change a shared Live View. Without viewId, makes a Live View (name and cameraIds required). With viewId, renames it or replaces its cameras. At most 36 cameras.
• delete_live_view: Delete a shared Live View. Needs viewId. Asks for confirmation.
• update_workflow_control: Turn "Workflows can share footage and identify people" on or off. Only a person can change it, from AI chat or the CCTV app, and it always asks for confirmation. While off, workflow steps that get footage images, make share links or identify people are shown but can't be turned on. Needs enabled. Asks for confirmation.

Share History and Recent Access for a facility's CCTV. links lists the share links that let someone outside the organisation watch the facility's recordings, with their status, expiry, views and who made them (never the link itself). access_log lists who viewed, downloaded, kept, released, edited or searched footage, newest first, including workflow steps and the AI Agent by name. People are named, never shown by email. To make or revoke a link use cctv_sharing_write.

Actions:

• links: List share links. Newest first; status narrows to active, expired or revoked links. Page with cursor.
• access_log: List Recent Access. Each entry has when, the action, who (a person's name, a workflow by name, or the AI Agent), the recordingId when it was about a recording, and what was accessed. Entries by organisation admins show only to callers with organisation-wide CCTV access, as in the app. Page with cursor.

Share links let someone outside the organisation (an insurer, the police, a contractor) watch a facility's CCTV recordings in the browser until the link expires. create_link makes one and returns its url, the only time a url is returned; people can make links for up to 7 days, workflow steps and Agent devices for up to 24 hours, and only while "Workflows can share footage and identify people" is on in CCTV settings. revoke_link stops a link working within a minute, and restore makes a revoked one work again. Every link and who made it shows in Share History (cctv_sharing_read links).

Actions:

• create_link: Make a share link. Returns { link, url, expiresAt }. Send the url to whoever needs to watch the footage. expiresInHours defaults to 24. Asks for confirmation.
• revoke_link: Revoke a share link. Anyone watching with the link is signed out within a minute. Revoking a revoked link changes nothing (revoked: false). Needs linkId.
• restore: Restore a revoked share link. Makes a revoked link work again until it expires. An expired link can't be restored; make a new one instead. Needs linkId. May ask for confirmation.
• update: Change a share link's description. Needs linkId, description.