Export Footage for an Investigation

This guide exports the video around an incident as an MP4 file you can store with a case, or share with a link. It takes four calls: find the moment, request a clip, wait for it to render, and download it.

You need an API key whose role can view the camera and its saved video. An OAuth app can follow the same steps with Authorization: Bearer <access token> in place of the API key headers; requesting and sharing a clip are write operations, so its grant needs the read and write scopes. Examples use the US host; EU organizations use api2.eu.rhombussystems.com and media.eu.rhombussystems.com.

1. Find the moment

If you already know the camera and the time, skip to step 2. To start from an alert, list the camera's recent alerts with getPolicyAlerts:

curl -X POST "https://api2.rhombussystems.com/api/event/getPolicyAlerts" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceFilter": ["CAMERA_UUID"], "afterTimestampMs": 1767225600000, "maxResults": 20}'

Each alert has a uuid, a timestampMs (when it started), a durationSec and, for camera alerts, the deviceUuid. Note the alert's uuid in your case record.

2. Request a clip

Ask for the footage with spliceV3: the camera, the start time in epoch milliseconds, and the length in seconds. Start a little before the event and run a little past it:

import os
import time
import requests

API = "https://api2.rhombussystems.com/api"
HEADERS = {"x-auth-scheme": "api-token", "x-auth-apikey": os.environ["RHOMBUS_API_KEY"]}

def call(path, body):
    response = requests.post(f"{API}/{path}", headers=HEADERS, json=body)
    response.raise_for_status()
    data = response.json()
    if data.get("error"):
        raise RuntimeError(data.get("errorMsg"))
    return data

alert_ms = 1767230000000  # the alert's timestampMs
clip = call("video/spliceV3", {
    "deviceUuids": ["CAMERA_UUID"],
    "startTimeMillis": alert_ms - 30_000,  # 30 seconds before
    "durationSec": 120,
    "title": "Case 2026-0142: loading dock",
    "description": "Alert AAAAAAAAAAAAAAAAAAAAAA",
})
clip_uuid = clip["clipUuid"]

The clip renders in the background, so the call returns at once with its clipUuid. Clip creation has a per-camera limit: if the call returns 429, wait the number of seconds in Retry-After before trying that camera again.

3. Wait for it to render

Poll getClipWithProgress every few seconds until status is COMPLETE. INITIATING, UPLOADING and RENDERING mean it's still in progress, and percentComplete shows how far along the current step is; any other status means it won't complete:

IN_PROGRESS = {"INITIATING", "UPLOADING", "RENDERING"}
deadline = time.time() + 30 * 60
while True:
    saved = call("event/getClipWithProgress", {"clipUuid": clip_uuid})["clip"]
    if saved["status"] == "COMPLETE":
        break
    if saved["status"] not in IN_PROGRESS or time.time() > deadline:
        raise RuntimeError(f"clip {clip_uuid} is {saved['status']}")
    time.sleep(5)

region = saved["clipLocation"]["region"]

How long rendering takes depends on the clip's length and on whether the camera has already uploaded that footage.

4. Download the MP4

Download the finished clip from the media host, using the region from step 3 and the same API key headers:

media = f"https://media.rhombussystems.com/media/metadata/{region}/{clip_uuid}.mp4"
with requests.get(media, headers=HEADERS, stream=True) as response:
    response.raise_for_status()
    with open(f"{clip_uuid}.mp4", "wb") as out:
        for chunk in response.iter_content(chunk_size=1 << 20):
            out.write(chunk)

curl "https://media.rhombussystems.com/media/metadata/REGION/CLIP_UUID.mp4" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -o clip.mp4

The media host takes the same credentials as the REST API: the API key headers, or Authorization: Bearer <access token> for an OAuth token with the read scope. To let a browser download the clip, give it a federated token as query parameters (?x-auth-scheme=federated-token&x-auth-ft=<token>); a token minted with deviceUUid can fetch the clip only if every camera in it is that device. Media and streams covers the media host, including streaming a clip inline instead of downloading it.

Share instead of download

To give someone outside your organization access without sending a file, create a share page with createSharedClipGroupV3. It takes the clip UUIDs, an optional password and an expiry, and returns a shareUrl:

{
  "uuids": ["CLIP_UUID"],
  "title": "Case 2026-0142",
  "plaintextPassword": "a-long-random-passphrase",
  "expirationTimeSecs": 1769904000
}

expirationTimeSecs is the Unix time (in seconds) when the link stops working, not a duration. Anyone with the link and the password can watch until then.

Keep a record

For each export, store the alert uuid, the clipUuid, the camera, the time range you requested, who requested it and when. Actions taken with an API key appear in your organization's audit log under the key's name; see Permissions and key rotation.