Hybrid gateway integration uses the cloud VMS and the on-prem VMS directly. The curls below are the calls to make.
These are the variables you will need to connect the gateways and cameras to those gateways:
VMS_HOST="https://your-tenant.cloud-vms.com"
LKEY="your-lkey"
SITE_GROUP_TOKEN="site-group-token"
RESOLVER_URL="https://resolver.example/path"
RESOLVER_USER="resolver-user"
RESOLVER_PASS="resolver-pass"
HUB_URL="https://hub.example"
HUB_API_KEY="hub-api-key"
GATEWAY_ENDPOINT="https://gateway.site-a.customer.cloud-vms.com"
Writes to the cloud VMS use api/v3 and Authorization: LKey. The cloud playback token is read from api/v5 with Authorization: SI and the site group token. That token is the token field on the channel group named Site{siteId}.
The on-prem host, or gateway_endpoint follows the pattern
https://gateway.{instanceName}.{customerName}.{domain}/.
instanceName: this can be set by the customer
customerName: this is set in the environment variables as one instance of CloudTwo will only use one customer Name
domain: is cloud-vms.com by default unless HUB_DOMAIN_NAME is set.
Register a Gateway
The user should provide:
site - siteId corresponding with an existing site on the instance
gateway name - string, can be anything will be shown to the user to identify the gateway
gateway username - string, username set for this gateway
gateway password - string, password set for this gateway
instance name - will be used to formulate the URL for this gateway. You can get this when the hybrid gateway is delpoyed
retention - int, retention time by default set in days. Should be between 1 - 3.
-
Ensure this gateway isn’t already registered on the service.
Authorizationis the gateway ID:
curl "$RESOLVER_URL?serial_id=GATEWAY-ID" \
-H "Accept: application/json" \
-H "Authorization: GATEWAY-ID"
A response that contains an id means this gateway ID is already registered. This is the same as our other gateway implementations
-
Create a gateway channel. You will also use the existing gateways method to do this ie v3/channels and setting the following meta. You will also need to attach this to this sites group token.
curl -X POST "$VMS_HOST/api/v3/channels/" \
-H "Authorization: LKey $LKEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Site A hybrid",
"timezone": "UTC",
"rec_mode": "off",
"hosting_mode": "off",
"source": { "url": "https://camera-proxy.example/uplink_camera/" },
"meta": {
"gateway": "gateway",
"gateway_id": "GATEWAY-ID",
"GATEWAY-ID": "gateway_id",
"gateway_username": "admin",
"gateway_password": "secret",
"max_num_cameras": 64,
"rsid": "GATEWAY-ID",
"planId": "NOPLAN",
"siteId": 123,
"123": "siteId",
"retention_time": 3,
"hybridvms": "hybridvms",
"instance_name": "site-a",
"gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/"
}
}'
-
Regsiter the gateway with the resolver service. Save the access_token.all from the created gateway channel response to use as the
access_token.
curl -X POST "$RESOLVER_URL" \
-u "$RESOLVER_USER:$RESOLVER_PASS" \
-H "Content-Type: application/json" \
-d '{
"serial_id": "GATEWAY-ID",
"password": "GATEWAY-ID",
"access_token": "CHANNEL_ACCESS_TOKEN_ALL"
}'
-
Register the gateway with the uplink hub. This call will register the hostname
curl -X POST "$HUB_URL/api/v1/groups/" \
-H "Content-Type: application/json" \
-H "X-API-Key: $HUB_API_KEY" \
-d '{
"name": "Site A hybrid",
"site_name": "site-a",
"customer_name": "customer",
"domain_name": "cloud-vms.com",
"channel_id": 456,
"forward_name": "camera-gateway-http"
}'
-
Update gateway meta with the hub group id. The previous call (step 4) will return an
id. You will need to save it to the newly created gateway channel asmeta.hub_group_id
curl -X PUT "$VMS_HOST/api/v3/channels/456/" \
-H "Authorization: LKey $LKEY" \
-H "Content-Type: application/json" \
-d '{
"meta": {
"gateway": "gateway",
"gateway_id": "GATEWAY-ID",
"GATEWAY-ID": "gateway_id",
"gateway_username": "admin",
"gateway_password": "secret",
"max_num_cameras": 64,
"rsid": "GATEWAY-ID",
"planId": "NOPLAN",
"siteId": 123,
"123": "siteId",
"retention_time": 30,
"hybridvms": "hybridvms",
"instance_name": "site-a",
"gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/",
"hub_group_id": "group-abc-123" // new id from hub url
}
}'
Add a camera to the gateway
-
Create the camera channel.
gatewayChannelIdis the gateway channel id from the previous step. This is also using the same method as the existing gateways, ip, http and rtsp coming from the user input when adding the camera. Add this channel toSite123the same way as the gateway.
curl -X POST "$VMS_HOST/api/v3/channels/" \
-H "Authorization: LKey $LKEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Lobby",
"timezone": "America/New_York",
"rec_mode": "off",
"events_enabled": false,
"source": {
"login": "admin",
"password": "secret",
"url": "https://camera-proxy.example/uplink_camera/",
"onvif_rtsp_port_fwd": 554
},
"meta": {
"gateway_cam": "gateway_cam",
"gateway_id": "GATEWAY-ID",
"GATEWAY-ID": "gateway_id",
"gateway_ip": "192.168.1.50",
"gateway_http": 80,
"gateway_rtsp": 554,
"siteId": 123,
"123": "siteId",
"gatewayChannelId": 456,
"hybridvms": "hybridvms",
"instance_name": "site-a",
"gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/"
}
}'
-
Get the gateway auth token. Log in with the gateway username and password stored on the gateway channel. The response field is
token. Send it asAuthorization: Tokenon every later on-prem call.
curl -X POST "$GATEWAY_ENDPOINT/api/auth-token/" \
-H "Content-Type: application/json" \
-d '{ "username": "admin", "password": "secret" }'
GATEWAY_TOKEN="token-from-auth-response"
-
Register the camera to the gateway.
access_tokenisaccess_tokens.allfrom the camera channel. The path id on the on-prem VMS is the cloud channel id.
curl -X POST "$GATEWAY_ENDPOINT/api/add-camera/" \
-H "Content-Type: application/json" \
-H "Authorization: Token $GATEWAY_TOKEN" \
-d '{
"ip": "192.168.1.50",
"http_port": "80",
"rtsp_port": "554",
"is_active": false,
"pid": null,
"access_token": "CAMERA_ACCESS_TOKEN_ALL",
"rtsp_only": "0",
"username": "admin",
"password": "secret",
"name": "Lobby",
"retention_time": 30
}'
Cloud and local playback
The switch only changes which token the player receives. It does not change where video is recorded.
Cloud playback uses the token field from api/v5. Pass that value to the player.
curl "$VMS_HOST/api/v5/channels/789/" \
-H "Authorization: SI $SITE_GROUP_TOKEN"
Local playback uses the on-prem camera record. Log in first with the same gateway auth call as in step 2 of creating the camera, then:
curl "$GATEWAY_ENDPOINT/api/camera/789" \
-H "Authorization: Token $GATEWAY_TOKEN"
{
"local_token": "<on-site playback token>",
"access_token": "<cloud playback token>",
"process_mode": "none"
}
Pass local_token to the same player. access_token in this body is the cloud token stored on the gateway. Either that value or the v5 token can play through the cloud. If local_token is missing, local playback is unavailable.
5. Copy events or recordings to the cloud
Recording stays on the local VMS until you set process_mode.
curl -X POST "$GATEWAY_ENDPOINT/api/edit-camera/789/" \
-H "Content-Type: application/json" \
-H "Authorization: Token $GATEWAY_TOKEN" \
-d '{ "process_mode": "event_and_record_sync" }'
|
|
Meaning |
|---|---|
|
|
Do not copy events or recordings to the cloud. |
|
|
Copy events only. |
|
|
Copy events and recorded video. |
Read the current value from process_mode on:
curl "$GATEWAY_ENDPOINT/api/camera/789/" \
-H "Authorization: Token $GATEWAY_TOKEN"
The same edit call updates the camera when its address, ports, login, or name change. Send only the fields that changed.
curl -X POST "$GATEWAY_ENDPOINT/api/edit-camera/789/" \
-H "Content-Type: application/json" \
-H "Authorization: Token $GATEWAY_TOKEN" \
-d '{
"ip": "192.168.1.51",
"http_port": "80",
"rtsp_port": "554",
"username": "admin",
"password": "secret",
"name": "Lobby east"
}'
To change retention for every camera, update the gateway channel, then edit each camera. Include the existing meta when you put the channel.
curl -X PUT "$VMS_HOST/api/v3/channels/456/" \
-H "Authorization: LKey $LKEY" \
-H "Content-Type: application/json" \
-d '{
"meta": {
"retention_time": 14,
"hybridvms": "hybridvms",
"gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/"
}
}'
curl -X POST "$GATEWAY_ENDPOINT/api/edit-camera/789/" \
-H "Content-Type: application/json" \
-H "Authorization: Token $GATEWAY_TOKEN" \
-d '{ "retention_time": 14 }'
Remove
Delete each camera on the on-prem VMS first, then delete its cloud channel.
curl -X DELETE "$GATEWAY_ENDPOINT/api/cameras/789/" \
-H "Authorization: Token $GATEWAY_TOKEN"
curl -X DELETE "$VMS_HOST/api/v3/channels/789/" \
-H "Authorization: LKey $LKEY"
When no cameras remain, delete the hub group, the resolver registration, restart the gateway, and delete the gateway channel.
curl -X DELETE "$HUB_URL/api/v1/groups/group-abc-123" \
-H "X-API-Key: $HUB_API_KEY"
curl -X DELETE "$RESOLVER_URL?serial_id=GATEWAY-ID" \
-u "$RESOLVER_USER:$RESOLVER_PASS"
curl -X POST "$GATEWAY_ENDPOINT/api/restart" \
-H "Authorization: Token $GATEWAY_TOKEN"
curl -X DELETE "$VMS_HOST/api/v3/channels/456/" \
-H "Authorization: LKey $LKEY"