Video

Get exact frame data

Fetches and returns the bytes, base64 encoded, of the frame at the given timestamp for a device. Use this instead of getExactFrameUri if, for whatever reason, either the URI is not useful or the client is unable to hit the media servers. The response always has HTTP status 200; check the status field, frameData is only set when it is AVAILABLE.

POST/api/video/getExactFrameData

Authorizations

x-auth-apikeystringheaderrequired

Your Rhombus API key. Must be accompanied by the x-auth-scheme header set to api-token (or partner-api-token for partner endpoints).

Authorizationstringheader

Instead of an API key, an OAuth access token: Bearer <token>, with the read scope.

OAuth explains tokens and scopes.

Headers

x-auth-schemeenum<string>headerdefault: api-token

Authentication scheme identifier. Use api-token or partner-api-token with the x-auth-apikey header, api or partner-api with x-auth-apikey plus a client certificate, api-oauth-token or partner-api-oauth-token with x-auth-access-token, and federated-token with x-auth-ft. A request with Authorization: Bearer <token> and no x-auth-scheme is treated as OAuth, and federated-token may also be sent as the x-auth-scheme and x-auth-ft query parameters.

Available options: api-token, api, api-oauth-token, federated-token, partner-api-token, partner-api, partner-api-oauth-token

x-auth-orgstring<RUUID>header

Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry Deprecation and Sunset: Tue, 05 Jan 2027 00:00:00 GMT). A malformed value returns 400 INVALID_AUTH_ORG; a client organization the partner cannot access returns 403 PARTNER_CLIENT_ACCESS_DENIED.

Length: 22 to 22

Body

application/json · object

Request object for fetching the bytes of an exact frame from a camera.

cameraUuidstring<DeviceFacetUuid> | nullbodyrequired

RUUID with optional appended facet information

Example: "AAAAAAAAAAAAAAAAAAAAAA.v0"

downscaleFactorinteger<int32> | nullbody

Ratio to shrink the image pixels by. Defaults to 1 (full resolution).

Range: 1 to …

permyriadCropHeightinteger<int32> | nullbody

Precise ratio to crop the height by. Capped at 10000, which is 100.00% of the image

Range: 0 to 10000

permyriadCropWidthinteger<int32> | nullbody

Precise ratio to crop the width by. Capped at 10000, which is 100.00% of the image

Range: 0 to 10000

permyriadCropXinteger<int32> | nullbody

Proportional location to start horizontal crop at. Where 10000 is 100.00% of, or the end of the image

Range: 0 to 10000

permyriadCropYinteger<int32> | nullbody

Proportional location to start vertical crop at. Where 10000 is 100.00% of, or the end of the image

Range: 0 to 10000

timestampMsinteger<int64> | nullbodyrequired

Timestamp in epoch milliseconds

bash

curl --request POST \
  --url 'https://api2.rhombussystems.com/api/video/getExactFrameData' \
  --header 'x-auth-scheme: api-token' \
  --header 'x-auth-apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "cameraUuid": "AAAAAAAAAAAAAAAAAAAAAA.v0",
    "downscaleFactor": 1,
    "permyriadCropHeight": 0,
    "permyriadCropWidth": 0,
    "permyriadCropX": 0,
    "permyriadCropY": 0,
    "timestampMs": 0
  }'

import requests

url = "https://api2.rhombussystems.com/api/video/getExactFrameData"
headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "cameraUuid": "AAAAAAAAAAAAAAAAAAAAAA.v0",
    "downscaleFactor": 1,
    "permyriadCropHeight": 0,
    "permyriadCropWidth": 0,
    "permyriadCropX": 0,
    "permyriadCropY": 0,
    "timestampMs": 0
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

const response = await fetch('https://api2.rhombussystems.com/api/video/getExactFrameData', {
  method: 'POST',
  headers: {
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "cameraUuid": "AAAAAAAAAAAAAAAAAAAAAA.v0",
    "downscaleFactor": 1,
    "permyriadCropHeight": 0,
    "permyriadCropWidth": 0,
    "permyriadCropX": 0,
    "permyriadCropY": 0,
    "timestampMs": 0
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);

console.log(await response.json());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "cameraUuid": "AAAAAAAAAAAAAAAAAAAAAA.v0",
              "downscaleFactor": 1,
              "permyriadCropHeight": 0,
              "permyriadCropWidth": 0,
              "permyriadCropX": 0,
              "permyriadCropY": 0,
              "timestampMs": 0
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api2.rhombussystems.com/api/video/getExactFrameData"))
            .header("x-auth-scheme", "api-token")
            .header("x-auth-apikey", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

json

{
  "error": false,
  "errorCode": "<string>",
  "frameData": "<string>",
  "mimeType": "image/jpeg",
  "responseMessage": "Frame retrieved successfully",
  "status": "AVAILABLE"
}

Response

200 OK

application/json · object

Response object containing the bytes of the requested frame data in base64 format

errorboolean | null

errorCodestring | null

Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg.

errorMsgstring | null

frameDatastring | null

Base64-encoded image bytes for the requested frame. Null if no frame could be retrieved.

mimeTypestring | null

MIME type of the encoded frame data

Example: "image/jpeg"

responseMessagestring | null

Human-readable message describing the result

Example: "Frame retrieved successfully"

statusenum<string>

Outcome of an exact frame request. AVAILABLE is the only value under which a frame URI or frame data is returned; every other value explains why the frame cannot be served.

Available options: AVAILABLE, FUTURE_TIMESTAMP, CAMERA_DELETED, CAMERA_STATE_UNAVAILABLE, CAMERA_NOT_CONNECTED, MEDIA_STORAGE_DEVICE_NOT_CONNECTED, NOT_RECORDING_AT_TIMESTAMP, NO_FOOTAGE_AT_TIMESTAMP, MEDIA_ADDRESS_UNAVAILABLE, FRAME_RETRIEVAL_FAILED

warningMsgstring | null

Errors

Like every operation, this one can also answer with the standard error body (errorCode, errorMsg). Errors explains each status and how to retry.

400 Bad Request. errorCode is one of: BAD_REQUEST, VALIDATION_FAILED, MISSING_REQUIRED_FIELD, INVALID_JSON, INVALID_REQUEST_BODY, FEATURE_NOT_ENABLED, INVALID_AUTH_ORG, LOCATION_NOT_FOUND.
401 Unauthorized. errorCode is one of: UNAUTHENTICATED, INVALID_CREDENTIAL, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CERTIFICATE_MISMATCH.
403 Forbidden. errorCode is one of: FORBIDDEN, DOMAIN_NOT_ALLOWED, DEVICE_SCOPE_MISMATCH, ROLE_NOT_PERMITTED, FUNCTIONALITY_REQUIRED, PARTNER_FUNCTIONALITY_REQUIRED, PERMISSION_REQUIRED, PARTNER_CLIENT_ACCESS_DENIED, HARDWARE_NOT_AVAILABLE, HARDWARE_ALREADY_REGISTERED, PARTNER_PORTAL_NOT_ENABLED, MANAGED_BY_MSP, SUPER_ADMIN_RESTRICTED_BY_MSP, MSP_DESIGNATION_INVALID, NOT_MANAGED_CLIENT.
429 Too Many Requests. errorCode is one of: RATE_LIMITED.
500 Internal Server Error. errorCode is one of: INTERNAL_ERROR.
503 Service Unavailable. errorCode is one of: SERVICE_UNAVAILABLE.