Преминете към основното съдържание
API docs by Redocly

Entrosity Sphere Portal API (0.1.0)

Download OpenAPI specification:Download

Entrosity Sphere portal REST API: video management for network video recorders (Dahua NVRs) - live view, playback, PTZ and alarms. This file is the source of truth for the backend server interfaces (oapi-codegen), request validation, and the frontend types (openapi-typescript). Run make gen after editing.

Authentication: Authorization: Bearer <product token>: users sign in on Entrosity Hub, which issues five-minute product tokens for Sphere (POST /api/platform/v1/auth/product-token {"product":"sphere"}, with the Hub's session cookie). Users, tenants (the Hub's organizations) and roles are managed on the Hub; Sphere keeps a copy.

Every route's access rule (public, authenticated, global admin, tenant permission) is declared in internal/http/portal/access.go and enforced before the handler runs.

system

Liveness probe

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

auth

Short-lived token for a tenant live stream (EventSource)

Returns a token valid for 60 seconds that opens GET /tenants/{tenantID}/stream?sse_token= for the given tenant and the caller's session. Access to the tenant is checked when the stream opens. Keeps the access token out of URLs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
tenant_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_in": 0
}

The signed-in user with their tenants and roles

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "display_name": "string",
  • "status": "active",
  • "is_global_admin": true,
  • "memberships": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

admin

Cross-tenant counters

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "tenants_total": 0,
  • "tenants_active": 0,
  • "global_admins": 0,
  • "tenant_users": 0,
  • "nvrs_total": 0,
  • "nvrs_online": 0,
  • "nvrs_failing": 0,
  • "cameras_total": 0,
  • "connectors_total": 0,
  • "connectors_online": 0,
  • "alarms_unacked": 0,
  • "streams_active": 0,
  • "tenants": [
    ]
}

Stored connector releases, with download links

Every stored Sphere connector installer (the newest ten), newest first, each with a link that needs no sign-in until download_expires_at; current marks the release connectors are updated to (SPHERE_CONNECTOR_UPDATE_CHANNEL). adoption counts the enrolled connectors by version. Empty when releases are off.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "adoption": [
    ],
  • "update_channel": "stable",
  • "releases_enabled": true,
  • "public_key": "string"
}

List tenants

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
string (TenantStatus)
Enum: "active" "suspended"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Global admins (the platform admins of Entrosity Hub)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Cross-tenant audit log

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
tenant_id
string <uuid>
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

tenant

Tenant profile

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change the tenant's settings (the name is the Hub's)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
object (TenantSettings)
default_timezone
string <= 64 characters

IANA time zone shown for NVRs without a site (default UTC).

object (TenantRetention)

Overrides of the server's retention windows (sent as a whole).

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Counters, NVR health and the last day's alarms

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "connectors_total": 0,
  • "connectors_online": 0,
  • "nvrs_total": 0,
  • "nvrs_online": 0,
  • "nvrs_failing": 0,
  • "cameras_total": 0,
  • "cameras_enabled": 0,
  • "streams_active": 0,
  • "sites_total": 0,
  • "alarms_today": 0,
  • "alarms_unacked": 0
}

Tenant members and their roles (managed on Entrosity Hub)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Sites of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a site (its connectors and NVRs stay, without a site)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Audit log of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

connectors

Connector enrollment tokens of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a connector enrollment token (the secret is returned once)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
label
string <= 200 characters
site_id
string <uuid>
expires_at
string <date-time>
max_uses
integer [ 1 .. 100000 ]

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "max_uses": 1
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "secret": "string",
  • "install_command": "string",
  • "cli_command": "string",
  • "download_url": "string"
}

Revoke an enrollment token

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Delete an enrollment token permanently (global admins; requires the password)

Global admins confirm with their own password: they send step_up_token, which Entrosity Hub issues for the password (POST /api/platform/v1/auth/step-up, product sphere).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>
Request Body schema: application/json
required
step_up_token
required
string [ 1 .. 4096 ] characters

Responses

Request samples

Content type
application/json
{
  • "step_up_token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

The newest connector installer, with a download link

The release connectors are updated to (SPHERE_CONNECTOR_UPDATE_CHANNEL). download_url needs no sign-in and works until download_expires_at. 404 when no release has been published.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "version": "0.1.0",
  • "channel": "stable",
  • "sha256": "string",
  • "size_bytes": 0,
  • "notes": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "download_url": "string",
  • "download_expires_at": "2019-08-24T14:15:22Z"
}

Sphere connectors of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get a connector

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "nvr_count": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Rename a connector or move it to a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>
Request Body schema: application/json
required
name
string <= 200 characters
site_id
string <uuid>
clear_site
boolean

Remove the connector from its site.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "nvr_count": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Remove a connector (409 connector_has_nvrs while it drives NVRs)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

A connector job (NVR test, recordings search, PTZ, streams)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
jobID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "nvr_id": "d377c949-6d3e-4fed-85af-98daf097ef9d",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

nvrs

The tenant's NVRs

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
site_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an NVR behind a connector (connects to it unless connect is false)

The password is stored encrypted and never returned. 409 nvr_address_taken when the connector already drives an NVR at that address and port.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
connector_id
required
string <uuid>
site_id
string <uuid>
name
required
string [ 1 .. 200 ] characters
driver
required
string (NvrDriver)
Enum: "dahua" "simulator"

simulator is a software NVR built into the connector, for trials and tests.

host
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9.:\[\]-]+$
port
integer [ 1 .. 65535 ]
Default: 80
https
boolean
Default: false
rtsp_port
integer [ 1 .. 65535 ]
Default: 554
timezone
string <= 64 characters
username
required
string [ 1 .. 128 ] characters
password
required
string <= 256 characters
connect
boolean
Default: true

Sign in right away.

Responses

Request samples

Content type
application/json
{
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "driver": "dahua",
  • "host": "string",
  • "port": 80,
  • "https": false,
  • "rtsp_port": 554,
  • "timezone": "string",
  • "username": "string",
  • "password": "string",
  • "connect": true
}

Response samples

Content type
application/json
{
  • "nvr": {
    },
  • "cameras": [
    ]
}

An NVR with its cameras

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "nvr": {
    },
  • "cameras": [
    ]
}

Rename an NVR, move it to a site or change its address

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
site_id
string <uuid>
clear_site
boolean
host
string [ 1 .. 255 ] characters ^[A-Za-z0-9.:\[\]-]+$
port
integer [ 1 .. 65535 ]
https
boolean
rtsp_port
integer [ 1 .. 65535 ]
timezone
string <= 64 characters

Empty clears it.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true,
  • "host": "string",
  • "port": 1,
  • "https": true,
  • "rtsp_port": 1,
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "dahua",
  • "host": "string",
  • "port": 0,
  • "https": true,
  • "rtsp_port": 0,
  • "timezone": "string",
  • "username": "string",
  • "desired_state": "connected",
  • "status": "unknown",
  • "status_error": "string",
  • "device_type": "string",
  • "serial": "string",
  • "firmware": "string",
  • "channel_count": 0,
  • "camera_count": 0,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove an NVR (the connector signs out and forgets it)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Change the user name and password the connector signs in with

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>
Request Body schema: application/json
required
username
required
string [ 1 .. 128 ] characters
password
required
string <= 256 characters

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "dahua",
  • "host": "string",
  • "port": 0,
  • "https": true,
  • "rtsp_port": 0,
  • "timezone": "string",
  • "username": "string",
  • "desired_state": "connected",
  • "status": "unknown",
  • "status_error": "string",
  • "device_type": "string",
  • "serial": "string",
  • "firmware": "string",
  • "channel_count": 0,
  • "camera_count": 0,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Sign in to the NVR (stay connected, receive alarms, serve video)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "dahua",
  • "host": "string",
  • "port": 0,
  • "https": true,
  • "rtsp_port": 0,
  • "timezone": "string",
  • "username": "string",
  • "desired_state": "connected",
  • "status": "unknown",
  • "status_error": "string",
  • "device_type": "string",
  • "serial": "string",
  • "firmware": "string",
  • "channel_count": 0,
  • "camera_count": 0,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Sign out of the NVR (its streams stop)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "name": "string",
  • "driver": "dahua",
  • "host": "string",
  • "port": 0,
  • "https": true,
  • "rtsp_port": 0,
  • "timezone": "string",
  • "username": "string",
  • "desired_state": "connected",
  • "status": "unknown",
  • "status_error": "string",
  • "device_type": "string",
  • "serial": "string",
  • "firmware": "string",
  • "channel_count": 0,
  • "camera_count": 0,
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Sign in once, describe the NVR and refresh its cameras

Creates an sphere.nvr.test job; poll GET /tenants/{tenantID}/jobs/{jobID} (or watch job.update) for its result, an NvrTestResult. On success the NVR's details and cameras are updated. 409 connector_offline when the connector is not connected.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "nvr_id": "d377c949-6d3e-4fed-85af-98daf097ef9d",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

Shorten the cameras' sub-stream keyframe interval for a quicker live picture

Changes the NVR's settings: every camera's sub stream (the one live grids show) gets a keyframe at least every keyframe_seconds (its frame rate × that many frames). A viewer joining a stream waits for the next keyframe before the picture shows, so this bounds the wait. Main streams, which the NVR records, are never changed, and shorter intervals are kept. Each channel is then checked in its sub stream: a camera that keeps a longer interval than the NVR stores is reported as not changed. Creates an sphere.nvr.tune_live job; its result is an NvrLiveTuneResult. 409 connector_offline when the connector is not connected.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>
Request Body schema: application/json
optional
keyframe_seconds
integer [ 1 .. 4 ]
Default: 1

Responses

Request samples

Content type
application/json
{
  • "keyframe_seconds": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "nvr_id": "d377c949-6d3e-4fed-85af-98daf097ef9d",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

The NVR's recent connector jobs

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
nvrID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

cameras

The tenant's cameras (every NVR's channels)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
nvr_id
string <uuid>
site_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Rename a camera or hide it

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cameraID
required
string <uuid>
Request Body schema: application/json
required
label
string <= 200 characters
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "nvr_id": "d377c949-6d3e-4fed-85af-98daf097ef9d",
  • "nvr_name": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "channel": 0,
  • "name": "string",
  • "title": "string",
  • "label": "string",
  • "enabled": true,
  • "ptz": true,
  • "online": true,
  • "main_codec": "string",
  • "sub_codec": "string",
  • "nvr_status": "unknown"
}

Move a PTZ camera (start and stop a movement, go to or store a preset)

A movement runs from start until stop (hold-to-move); presets use start only. Cameras the NVR does not report as PTZ are not refused (detection is best effort). 409 nvr_offline or connector_offline. Commands expire after 5 seconds, so a late one never moves the camera.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cameraID
required
string <uuid>
Request Body schema: application/json
required
code
required
string (PtzCode)
Enum: "Up" "Down" "Left" "Right" "LeftUp" "RightUp" "LeftDown" "RightDown" "ZoomTele" "ZoomWide" "FocusNear" "FocusFar" "IrisLarge" "IrisSmall" "GotoPreset" "SetPreset" "ClearPreset"
action
required
string
Enum: "start" "stop"
speed
integer [ 1 .. 8 ]
preset
integer [ 1 .. 255 ]

Responses

Request samples

Content type
application/json
{
  • "code": "Up",
  • "action": "start",
  • "speed": 1,
  • "preset": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "nvr_id": "d377c949-6d3e-4fed-85af-98daf097ef9d",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

live

Watch a camera live or play back a recording

Returns a viewer session: play whep_url (WHEP) with Authorization: Bearer <token> and keep the session alive with POST /streams/{streamID}/keepalive every 15 seconds (it returns a fresh token). Live streams are shared by every viewer of the camera's profile; a playback is the viewer's own. Unwatched streams stop after 30 seconds. 409 stream_limit when the site's or the NVR's limit is reached, nvr_offline, connector_offline, camera_disabled.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
camera_id
required
string <uuid>
kind
string
Default: "live"
Enum: "live" "playback"
profile
string (StreamProfile)
Enum: "main" "sub"

main is full resolution; sub the NVR's low-resolution stream (grids).

start
string <date-time>

Playback from (playback only).

end
string <date-time>

Playback until

Responses

Request samples

Content type
application/json
{
  • "camera_id": "ecd971da-137d-4ab2-9c2f-7f6725ac305e",
  • "kind": "live",
  • "profile": "main",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "camera_id": "ecd971da-137d-4ab2-9c2f-7f6725ac305e",
  • "kind": "live",
  • "profile": "string",
  • "path": "string",
  • "whep_url": "string",
  • "token": "string",
  • "token_expires_at": "2019-08-24T14:15:22Z",
  • "state": "starting",
  • "error": "string",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z"
}

Keep watching (every 15 seconds); returns the state and a fresh token

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
streamID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "camera_id": "ecd971da-137d-4ab2-9c2f-7f6725ac305e",
  • "kind": "live",
  • "profile": "string",
  • "path": "string",
  • "whep_url": "string",
  • "token": "string",
  • "token_expires_at": "2019-08-24T14:15:22Z",
  • "state": "starting",
  • "error": "string",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z"
}

Stop watching

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
streamID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

playback

Search the camera's recordings on the NVR

Creates an sphere.recordings.find job; its result is a RecordingsResult. At most 7 days per search.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cameraID
required
string <uuid>
Request Body schema: application/json
required
from
required
string <date-time>
to
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "from": "2019-08-24T14:15:22Z",
  • "to": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "nvr_id": "d377c949-6d3e-4fed-85af-98daf097ef9d",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

alarms

The alarm log, newest first (keyset pagination)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
before_at
string <date-time>

Cursor from the previous page (next_before_at).

before_id
string <uuid>
from
string <date-time>
to
string <date-time>
nvr_id
string <uuid>
camera_id
string <uuid>
acked
boolean
code
Array of strings <= 20 items [ items <= 64 characters ]

Alarm codes (repeat the parameter for several).

limit
integer [ 1 .. 500 ]
Default: 100

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_before_at": "2019-08-24T14:15:22Z",
  • "next_before_id": "0ce7fc60-5733-4ae4-967b-4beb905a3fd7"
}

Acknowledge alarms (by id, or everything up to a moment)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
ids
Array of strings <uuid> <= 500 items [ items <uuid > ]
before
string <date-time>

Acknowledge every alarm up to this moment.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "before": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "acked": 0
}

views

Saved camera grids (shared ones and the user's own)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Save a camera grid

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
layout
required
integer
Enum: 1 4 6 8 9 16 25 36 64
cells
required
Array of strings or null <uuid> <= 64 items [ items <uuid > ]
shared
boolean
Default: false

Visible to the whole tenant (needs views:manage).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "layout": 1,
  • "cells": [
    ],
  • "shared": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "layout": 1,
  • "cells": [
    ],
  • "shared": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a saved grid (shared grids need views:manage)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
viewID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
layout
required
integer
Enum: 1 4 6 8 9 16 25 36 64
cells
required
Array of strings or null <uuid> <= 64 items [ items <uuid > ]
shared
boolean
Default: false

Visible to the whole tenant (needs views:manage).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "layout": 1,
  • "cells": [
    ],
  • "shared": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "layout": 1,
  • "cells": [
    ],
  • "shared": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a saved grid

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
viewID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

events

Live updates (server-sent events)

text/event-stream of the tenant's live updates: alarm.new (new alarms, an array), alarm.ack, nvr.status, stream.state, connector.status and job.update. Authenticate with a bearer token or, for EventSource, ?sse_token= from POST /auth/sse-token.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
sse_token
string <= 4096 characters

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}