Skip to main content

Alerts

An alert opens when a workflow's Create Alert step runs. See Alerts and clips for how triage works in the dashboard.

Statuses​

Alert status is one of:

StatusMeaning
openNew, nobody has handled it.
acknowledgedSomeone is looking at it.
resolvedHandled, with a resolution note.
dismissedClosed as noise or a false alarm.

The allowed moves are:

  • open → acknowledged, resolved or dismissed.
  • acknowledged → resolved or dismissed.
  • acknowledged, resolved or dismissed → open, with reopen.

A closed alert (resolved or dismissed) changes only through reopen. You can assign open and acknowledged alerts. A single action on an alert whose status doesn't allow it returns 409. A bulk action updates the alerts it can and lists the others under skipped.

Every action is recorded in the alert's history and in the audit log. The person who acts is always the signed-in user. An actor field in the body is accepted for older clients and ignored.

Every endpoint on this page works for operators and admins.

List alerts​

GET/alerts

Lists alerts, newest first. The X-Total-Count response header gives the number of matching alerts before limit and offset are applied.

Query parameters​

statusstringoptional
Only alerts with this status: open, acknowledged, resolved or dismissed. closed means resolved and dismissed. Separate several with commas, for example open,acknowledged.
assigned_tostringoptional
me for alerts assigned to you, unassigned for alerts nobody has, a user ID, or an exact assignee value.
camera_idintegeroptional
Only alerts from this camera.
camerastringoptional
Only alerts from the camera with this name.
limitintegeroptional
The most alerts to return, from 1 to 500. Defaults to 50.
offsetintegeroptional
How many matching alerts to skip, for paging. Defaults to 0.

Response fields​

An array of alerts:

idintegeroptional
The alert ID.
statusstringoptional
open, acknowledged, resolved or dismissed.
tsstringoptional
When the alert was raised.
rule_namestring or nulloptional
The name of the workflow that raised it.
camera_idintegeroptional
The camera ID.
camera_namestringoptional
The camera name.
severitystringoptional
The severity from the camera's detection profile: LOW, MEDIUM, HIGH or CRITICAL.
event_idintegeroptional
The rule event behind the alert. Use it with GET /clips/{event_id}.
clip_uristring or nulloptional
Where the clip is stored, or null while there is no clip.
clip_urlstringoptional
The API path to play the clip, such as /clips/134299. Only present when there is a clip.
captionstring or nulloptional
The clip caption, once written.
caption_statusstringoptional
PENDING, PROCESSING, COMPLETED or FAILED. See Video captions.
caption_generated_atstring or nulloptional
When the caption was written.
assigned_tostring or nulloptional
Who the alert is assigned to.
acknowledged_bystring or nulloptional
Who acknowledged it.
resolution_notesstring or nulloptional
The note added when it was resolved or dismissed.
resolved_atstring or nulloptional
When it was resolved or dismissed.

Responses​

200
The alerts.
401
You are not signed in.
422
A status value is not valid, or assigned_to is a user ID that doesn't exist.

Get an alert's history​

GET/alerts/{alert_id}/history

Lists every triage action on one alert, oldest first. Notes from earlier resolutions stay here after the alert is reopened.

Path parameters​

alert_idintegerrequired
The alert.

Response fields​

An array of entries:

idintegeroptional
The entry ID.
alert_idintegeroptional
The alert.
actionstringoptional
assigned, acknowledged, resolved, dismissed or reopened.
actorstring or nulloptional
Who did it.
notestring or nulloptional
The note, if any. For assigned, the new assignee.
tsstringoptional
When it happened.

Responses​

200
The history.
404
No alert with this ID.

Assign an alert​

POST/alerts/{alert_id}/assign

Sets who the alert is assigned to. The status doesn't change. Works on open and acknowledged alerts.

Path parameters​

alert_idintegerrequired
The alert.

Body​

assigned_tostringrequired
The person or team, for example an email address.

Response fields​

The updated alert: id, event_id, rule_id, status, assigned_to, resolution_notes, resolved_at, acknowledged_by and ts.

Responses​

200
The alert was assigned.
404
No alert with this ID.
409
The alert is closed. Reopen it first.

Acknowledge an alert​

POST/alerts/{alert_id}/acknowledge

Sets the status of an open alert to acknowledged and stores you in acknowledged_by.

Path parameters​

alert_idintegerrequired
The alert.

Body​

notestringoptional
A note for the alert's history.

Responses​

200
The alert was acknowledged. Returns the updated alert.
404
No alert with this ID.
409
The alert is not open.

Resolve an alert​

POST/alerts/{alert_id}/resolve

Sets the status to resolved, records the time and saves your note. Works on open and acknowledged alerts. A resolved alert no longer protects its event and clip from retention.

Path parameters​

alert_idintegerrequired
The alert.

Body​

notestringrequired
The resolution note. Stored in resolution_notes.

Responses​

200
The alert was resolved. Returns the updated alert.
404
No alert with this ID.
409
The alert is already closed.
422
note is missing.

Dismiss an alert​

POST/alerts/{alert_id}/dismiss

Sets the status to dismissed, for a false alarm or noise. Works on open and acknowledged alerts. Like a resolved alert, a dismissed alert no longer protects its event and clip from retention.

Path parameters​

alert_idintegerrequired
The alert.

Body​

notestringoptional
Why it was dismissed. Stored in resolution_notes.

Responses​

200
The alert was dismissed. Returns the updated alert.
404
No alert with this ID.
409
The alert is already closed.

Reopen an alert​

POST/alerts/{alert_id}/reopen

Moves an acknowledged, resolved or dismissed alert back to open. It clears resolved_at, resolution_notes and acknowledged_by on the alert. The earlier notes stay in its history.

Path parameters​

alert_idintegerrequired
The alert.

Body​

Optional.

notestringoptional
Why it was reopened.

Responses​

200
The alert was reopened. Returns the updated alert.
404
No alert with this ID.
409
The alert is already open.

Bulk actions​

These endpoints apply one action to several alerts at once:

EndpointBodyApplies to
POST /alerts/bulk-acknowledgealert_idsopen alerts
POST /alerts/bulk-resolvealert_ids, note (required)open and acknowledged alerts
POST /alerts/bulk-dismissalert_ids, note (optional)open and acknowledged alerts
POST /alerts/bulk-assignalert_ids, assigned_to (required)open and acknowledged alerts

If any ID doesn't exist, the request fails with 422 and nothing changes. Alerts whose status doesn't allow the action are left as they are and listed under skipped.

POST/alerts/bulk-resolve

Body​

alert_idsarray of integersrequired
The alerts. Must not be empty.
notestringoptional
The note for all of them. Required for resolve, optional for dismiss, not used for acknowledge.
assigned_tostringoptional
The assignee. Bulk assign only.

Response fields​

updatedintegeroptional
How many alerts were updated.
alert_idsarray of integersoptional
The IDs that were updated.
skippedarray of objectsoptional
Alerts left unchanged, each with id and its current status.
skipped_idsarray of integersoptional
The IDs of the skipped alerts.

Responses​

200
The eligible alerts were updated.
422
The list is empty, contains an ID that doesn't exist, or a required field is missing.
Was this page helpful?