Alerts API Reference: Endpoints and Examples

OpenAPI YAML OpenAPI JSON problems YAML API overview

This group has 6 operations, generated from api/openapi.yaml. Filter by path, action, or authentication. Each endpoint lists its inputs; expand it for a request template and response codes. Templates need your own values and a schema-valid body.

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

Alerts: open screen problems, acknowledge, snooze and mutes

GET/api/alerts¶

List Alerts

Lists the project's screen alerts: one per screen and condition while it lasts (open), and those that ended within the plan's event retention (resolved).

An alert opens when its condition's event arrives (screen.offline, a display_disconnected, temperature_high or on_battery health change, screen.storage_shortfall, a stuck screen.manifest_upgrade, an error-level screen.status_changed, a stalled, blank or frozen screen.glass_changed) and resolves on the clearing event; crashing is a notice, not an alert. counts.attention counts open alerts that are not acknowledged, snoozed or muted, the number the dashboard shows.

A screen restarting for a reboot the backend sent opens no screen_offline or display_disconnected alert until the reboot is done or ten minutes after it was sent; a condition that still holds then opens its alert at that moment. Open alerts come first, newest first; pass next_cursor back as before for the next page.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAlerts

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
format	query	optional	json (default) returns the report as JSON. csv, xlsx and pdf return the same rows as a file attachment (every page of a paged report, up to 50000 rows).
state	query	optional
screen_id	query	optional
before	query	optional	next_cursor of the previous page.
limit	query	optional

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/alerts'

Responses

Status	Meaning	Body and headers
200	One page of alerts.	AlertList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/alerts/{id}¶

Get Alert

One alert.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAlert

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/alerts/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The alert.	Alert (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/alerts/{id}/acknowledge¶

Acknowledge Alert

Acknowledges an open alert: someone is on it. Without until it stays acknowledged until it resolves; with until (at most 30 days ahead) it is snoozed and needs attention again at that instant if it is still open. While acknowledged or snoozed, a notification's notice about it that is still in its hold is skipped (acknowledged).

A later acknowledge replaces the earlier one. Appends screen.alert_acknowledged. A resolved alert is alert_not_open.

Authentication: projectBearer OR dashboardSession
Request body: AlertAcknowledge
Operation ID: acknowledgeAlert

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
until (optional, string)	Snooze until this instant, at most 30 days ahead. Absent: acknowledged until the alert resolves. format: "date-time"

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/alerts/RESOURCE_ID/acknowledge'

Responses

Status	Meaning	Body and headers
200	The acknowledged alert.	Alert (application/json)
409	alert_not_open.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/alert-mutes¶

List Alert Mutes

Lists the project's mutes that have not ended, soonest end first (at most 50).

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAlertMutes

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/alert-mutes'

Responses

Status	Meaning	Body and headers
200	The project's current mutes.	AlertMuteList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/alert-mutes¶

Create Alert Mute

Mutes screens for maintenance until an instant at most 30 days ahead: the screens named by screen_ids, and every screen carrying any of tags at the time a notice is due. Their alerts still open and resolve, marked muted, and never need attention; every notification's notices about them are skipped (muted).

An organization has at most 50 current mutes across its projects (alert_mute_limit_reached). Appends alert_mute.created.

Authentication: projectBearer OR dashboardSession
Request body: AlertMuteWrite
Operation ID: createAlertMute

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
screen_ids (optional, array)
tags (optional, ScreenTags)	Fleet selector tags, 0 to 16 unique exact tags, each matching the media tag grammar. On ScreenPatch the array replaces the whole set and an empty array clears it; a duplicate or malformed tag is invalid_request. Changing tags bumps the screen revision (If-Match guards it) and appends screen.updated with details.tags; it never changes the manifest revision. Tags are never on the runtime manifest and never authorization.
until (required, string)	At most 30 days ahead. format: "date-time"
note (optional, string)	maxLength: 200

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/alert-mutes'

Responses

Status	Meaning	Body and headers
201	Created.	AlertMute (application/json)
409	alert_mute_limit_reached or idempotency_mismatch.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/alert-mutes/{id}¶

Delete Alert Mute

Ends a mute now and appends alert_mute.deleted.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteAlertMute

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/alert-mutes/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Ended.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)