Create alarm applications with the Alta Video API

Last modified: Monday June 09, 2025.

Using the Alta Video API, you can develop custom applications to handle Alta Protect alarms.

The following examples outline three use cases. To learn more about the API, see Introducing: Alta Video API.

Required knowledge

• Basic programming skills.
• Web concepts (HTTP/S).
• Obtaining and using API keys and authentication tokens.
• Data formats and creating data structures, particularly in JSON.
• Programmatically constructing HTTP Requests (HTTP method, URL, headers, request body, and payload).
• Programmatically handling and parsing responses to extract relevant information.
• Configuring event detection using webhooks and gathering and formatting event data.
• Basic security practices, including storage and use of passwords and user IDs.

Authentication

You need to generate an authentication cookie to pass with your API requests.

• The cookie is obtained by sending an HTTP POST request to https://<deploymentname>.<region>.alta.avigilon.com/api/v1/dologin
• The body must include the JSON: {"username":"<username>","password":"<password>"}
• The username and password are the email and password you use to log into the deployment.
• The authentication cookie is in the response.

User permissions

Depending on the functionality of your application, the Alta Video user used to authenticate API calls must have the correct device and system permissions, such as View live video, View historic video, Share video, and so on.

• You can create a user, role, and user group with only the required permissions.
• For more information, see Manage Protect users..

View alarm video using a shared link

1. Configure a shared link and webhook as alarm actions for the zone.
2. Include the $alarmZoneId in the webhook payload.
3. When the webhook triggers, get a list of ongoing alarms using /api/v1/ongoingAlerts
4. Find the alarm guid by matching the alarm_zone_id in the response with the $alarmZoneId in the webhook payload.
5. Get a list of bookmarks for the alert using /api/v1/alerts/<guid>/bookmarks
6. Extract the guest_token from each bookmark.
7. Create and share a link to each video: https://<deploymentname>.<region>.alta.avigilon.com/cloud?t=<guest_token>

Verify an ongoing alarm

1. Configure a webhook as an alarm action for the zone.
2. Include the $alarmZoneId and $deviceId in the webhook payload.
3. When the webhook triggers, get a list of ongoing alarms using /api/v1/ongoingAlerts
4. In the response:
   1. Find the alarm guid by matching the alarm_zone_id with the $alarmZoneId in the webhook payload.
   2. Find if the alarm is merged. Similar detections within a short space of time are merged into a single ongoing alert.
   3. You can also extract the origin_name if you didn’t pass $deviceId in the webhook.
5. Change the verification status by posting the acknowledgment_code, guid, merged, and origin_name to /api/v1/alerts/<guid>
6. Pass the acknowledgment_code as:
   1. 101 for none
   2. 201 for valid
   3. 202 for false

End an ongoing alarm

1. Configure a webhook as an alarm action for the zone.
2. Include the $alarmZoneId in the webhook payload.
3. Get a list of ongoing alarms using /api/v1/ongoingAlerts
4. Find the alarm guid by matching the alarm_zone_id in the response with the $alarmZoneId in the webhook payload.
5. End the alarm by posting /api/v1/alerts/<guid>/end

Useful API calls

The following API calls are useful for creating Alta Protect applications. For a full list of API calls, see https://alta-video.readme.io/reference/get_api-v1-about.

• /api/v1/alarmZoneAlerts
• /api/v1/alarmZoneAlerts/stopLocalOngoing
• /api/v1/alarmZoneAlerts/{alert_id}/{sub_alert_id}/details
• /api/v1/alarmZones
• /api/v1/alarmZones/arm
• /api/v1/alarmZones/disarm
• /api/v1/alarmZones/{alarm_zone_id}/arm
• /api/v1/alarmZones/{alarm_zone_id}/disarm
• /api/v1/alarmZones/{id}
• /api/v1/alarmZones/{id}/comment
• /api/v1/alarmZones/{id}/logs
• /api/v1/alarmZonesUserMuted
• /api/v1/alarmZonesUserMuted/{id}
• /api/v1/alerts
• /api/v1/alerts/{guid}
• /api/v1/alerts/{guid}/bookmarks
• /api/v1/alerts/{guid}/end
• /api/v1/ongoingAlerts
• /api/v1/publicIntrusionEmergencyContacts
• /api/v1/publicIntrusionEmergencyContacts/{id}
• /api/v1/publicIntrusionWebhooks