Relay (third-party cameras)

Get third party camera discovery scan status

Returns the progress of the current/most-recent third-party camera discovery run in the org, so clients can show progress and distinguish not-started, in-progress, and complete (including complete-with-zero-cameras).

POST/api/relay/getThirdPartyCameraDiscoveryScanStatus

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 getting the progress of the current/most-recent third-party camera discovery run in the organization.

bash

curl --request POST \
  --url 'https://api2.rhombussystems.com/api/relay/getThirdPartyCameraDiscoveryScanStatus' \
  --header 'x-auth-scheme: api-token' \
  --header 'x-auth-apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api2.rhombussystems.com/api/relay/getThirdPartyCameraDiscoveryScanStatus"
headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {}

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

const response = await fetch('https://api2.rhombussystems.com/api/relay/getThirdPartyCameraDiscoveryScanStatus', {
  method: 'POST',
  headers: {
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
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 = """
            {}
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api2.rhombussystems.com/api/relay/getThirdPartyCameraDiscoveryScanStatus"))
            .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

{
  "camerasFound": 0,
  "error": false,
  "errorCode": "<string>",
  "hasRun": true,
  "inProgress": true,
  "nvrCount": 0,
  "nvrProgress": [
    {
      "camerasFound": 0,
      "currentIp": "<string>",
      "ipResults": [
        {
          "acceptedUsername": "<string>",
          "codec": "<string>",
          "ipAddress": "<string>",
          "macAddress": "<string>",
          "manufacturer": "<string>",
          "model": "<string>",
          "rtspFound": true,
          "source": "<string>",
          "status": "<string>",
          "statusDetail": "<string>"
        }
      ],
      "ipResultsTruncated": true,
      "ipsProbed": 0,
      "ipsTotal": 0,
      "nvrUuid": "<string>",
      "phase": "<string>",
      "scannedCidrs": [
        "<string>"
      ],
      "updatedMs": 0
    }
  ],
  "pendingCount": 0,
  "scanId": "<string>",
  "startedMs": 0
}

Response

200 OK

application/json · object

Progress of the current/most-recent third-party camera discovery run.

camerasFoundinteger<int32> | null

Number of cameras discovered so far in this run.

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

hasRunboolean | null

Whether discovery has ever been run for this org. When false, all other fields are unset/zero.

inProgressboolean | null

Whether a discovery run is still in progress (at least one Relay scan outstanding and the run is not stale).

nvrCountinteger<int32> | null

Total number of Relays (NVRs) this run is scanning.

nvrProgressobject[] | null

Per-Relay live scan progress and per-IP probe results (for troubleshooting).

Show child attributes

camerasFoundinteger<int32> | null

Cameras discovered by this Relay so far.

currentIpstring | null

IP currently being probed, if any.

errorMsgstring | null

Error message if this Relay's scan failed.

ipResultsobject[] | null

Per-IP probe results for troubleshooting.

Show child attributes

acceptedUsernamestring | null

Username of the credentials that succeeded, if any.

codecstring | null

Video codec(s) the device advertised over ONVIF (e.g. "H264"), if any.

ipAddressstring | null

The probed IP address.

macAddressstring | null

MAC address, if known.

manufacturerstring | null

Manufacturer reported over ONVIF, if any.

modelstring | null

Model reported over ONVIF, if any.

rtspFoundboolean | null

Whether an RTSP stream URI was obtained for this IP.

sourcestring | null

How the IP was found: MULTICAST (WS-Discovery) or PORT_SCAN (554 open).

statusstring | null

ONVIF probe outcome: GOOD, NOT_SUPPORTED, NOT_AUTHENTICATED, NO_ONVIF, NOT_REACHABLE.

statusDetailstring | null

Human-readable detail about the outcome — especially why a device that responded to ONVIF wasn't usable.

ipResultsTruncatedboolean | null

True if ipResults was capped (more IPs were probed than are listed).

ipsProbedinteger<int32> | null

IPs probed so far in the current phase.

ipsTotalinteger<int32> | null

IPs to ONVIF-probe in the current phase (0 while the phase is opaque, e.g. nmap).

nvrUuidstring | null

Relay (NVR) uuid this progress is for.

phasestring | null

DISCOVERING | PORT_SCANNING | PROBING | COMPLETE | FAILED.

scannedCidrsstring[] | null

Subnets/CIDRs being scanned (meaningful during the opaque port-scan phase).

updatedMsinteger<int64> | null

Epoch millis this progress was last updated.

pendingCountinteger<int32> | null

Number of Relays whose scan has not yet finished. Zero means the run is complete.

scanIdstring | null

Opaque id of the run, so clients can tell if a newer run superseded theirs.

startedMsinteger<int64> | null

Epoch millis when the run started.

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.