Alerts API

API v1

Overview

This API provides access to alerts entries and configurations. Alerts are grouping of events that happened all in close proximity of each other in the same location.

Authentication

This API requires a valid Bearer token in the Authorization header for every request. See API Authentication for how to request and use your token.

Endpoint

GET /api/v1/alerts/entries

Retrieves a list of alert entries for a given project. Optionally, results can be filtered using the since query parameter.

Request

• URL: /api/v1/alerts/entries
• Method: GET
• Authentication: Bearer token is required. Include the token in the request header.

Query Parameters:

• since (optional): A timestamp in ISO 8601 format to filter events created after the specified date. If not provided, recent alert entries will be returned.

Response

Returns a list of detection alert entries. Each alert entry contains the following fields:

Response Fields:

• id (string): Unique identifier for the alert entry.
• config_id (string): Unique identifier for the configuration for this entry.
• created_at (string): The timestamp of when the entry was created (in UTC).
• updated_at (string): The timestamp of when the entry was last updated (in UTC).
• title (string): The title of the configuration for this entry.
• acted_at (string | null): The timestamp at which an action was taken (in UTC), if any.
• action_taken: (string | null): The action taken.
• root_cause_set_at (string | null): The timestamp at which a root cause was set (in UTC), if any.
• root_cause (string | null): The root cause that was set.
• viewed_at (string | null): The first timestamp at which the alert was first opened on the dashboard (in UTC).
• acknowledged_at (string | null): The timestamp at which the alert was first acknowledged according to its acknowledgement mechanism (in UTC).
• dismissed_at (string | null): The first timestamp at which the alert was dismissed (in UTC).
• events (array<Detection>): Detections as defined in Detections API

Error Response

If the since parameter is invalid, the API returns a 400 error.

GET /api/v1/alerts/configs

Retrieves a list of alert configurations for a given project.

Request

• URL: /api/v1/alerts/configs
• Method: GET
• Authentication: Bearer token is required. Include the token in the request header.

Response

Returns a list of detection alert configs. Each alert config contains the following fields:

Response Fields:

• id (string): Unique identifier for the config.
• created_at (string): The timestamp of when the config was created (in UTC).
• updated_at (string): The timestamp of when the config was last updated (in UTC).
• title (string): The title of the configuration.
• preset_tags (array<AlertTag>): A list of tags (actions and root causes) that are shown by default on the dashboard.
• allow_custom_root_cause (boolean): Whether a free-text field should be shown to input a root cause.
• allow_custom_action (boolean): Whether a free-text field should be shown to input an action.
• ack_mechanisms (array<string>): Allowed acknowledgement mechanisms, one of 'button', 'view', 'act', 'set_root_cause'.
• silenced_until (string | null): The date until which this config is silenced (in UTC), if any.
• silenced_rois (array<AlertRoiSilence>): The silences for specific positions.
• time_window_seconds (int): The duration of the time window considered when creating an alert.
• min_events (int): The number of events within the time window that trigger an alert.
• rois (array<Roi>): The list of positions for which this config is relevant.
• labels (array<Label>): The list of detections for which this config is relevant.

AlertTag object

• tag_category (string): One of "action" or "root_cause".
• text (string): The name of the tag.

AlertRoiSilence object

• name (string): Region of interest where the alert is silenced.
• title (string): Title of the region of interest.
• api_name (string): Custom API name of the region of interest.
• silenced_until (string): The date until which this config is silenced (in UTC) for this ROI.

Roi object

• name (string): Region of interest where the alert is silenced.
• title (string): Title of the region of interest.
• api_name (string): Custom API name of the region of interest.

Label object

• name (string): Name for this type of detection.
• title (string): Title for this type of detection.