Last updated
Alerts
Alert rules that fire on LIVE events (webhook, email, in-app, Telegram).
Every operation authenticates with an API key (Authorization: Bearer <key>) and errors use the shared envelope described in Errors. Generated from the API’s OpenAPI document.
List alert deliveries
/v1/alerts/deliveriesOne row per rule, channel and event: delivered, failed (with detail and the attempts made) or capped (a plan cap such as the monthly webhook cap dropped it), newest first.
Query parameters
| Name | Type | Description |
|---|---|---|
ruleIdOptional | string | Only this rule (UUID). |
statusOptional | "delivered" | "failed" | "capped" | Only this outcome. |
sinceOptional | string | ISO 8601 time; only newer rows. |
limitOptional | integer | Rows to return. Range 1–200. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/alerts/deliveries" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "items": [ { "id": "5a7e0b0c-2d55-5f11-8b0e-0d0a3c5e6f70", "source": "alert", "ruleId": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "ruleName": "Envelopes from Linh", "channelType": "webhook", "eventType": "envelope", "status": "failed", "attempts": 4, "detail": "retry exhausted: webhook HTTP 503", "isTest": false, "createdAt": "2026-11-06T09:58:13.410Z" }, { "id": "a3d9c6e1-4b2f-5c8e-9a71-2e5b8d0f4c13", "source": "alert", "ruleId": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "ruleName": "Envelopes from Linh", "channelType": "in_app", "eventType": "envelope", "status": "delivered", "attempts": 1, "detail": null, "isTest": false, "createdAt": "2026-11-06T09:58:12.512Z" } ], "observedAt": "2026-11-06T09:58:13.410Z", "provenance": { "observedAt": "2026-11-06T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_history", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-history-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List alert fires
/v1/alerts/firesEvery time a rule matched an event, newest first, whether or not a channel delivered it (compare with deliveries).
Query parameters
| Name | Type | Description |
|---|---|---|
ruleIdOptional | string | Only this rule (UUID). |
sinceOptional | string | ISO 8601 time; only newer rows. |
limitOptional | integer | Rows to return. Range 1–200. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/alerts/fires" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "items": [ { "id": "1c3b5e86-0f43-5a3e-9d3c-5f6a1f0e7b21", "ruleId": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "ruleName": "Envelopes from Linh", "eventType": "envelope", "roomId": "7568123456789012345", "creatorUniqueId": "linh.live", "channelCount": 2, "isTest": false, "firedAt": "2026-11-06T09:58:12.104Z" } ], "observedAt": "2026-11-06T09:58:12.104Z", "provenance": { "observedAt": "2026-11-06T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_history", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-history-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List alert rules
/v1/alerts/rulesEvery rule of the workspace with its channels. Signing secrets are never returned again.
Request
curl "https://api.next.toktokdata.live/v1/alerts/rules" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "rules": [ { "id": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "name": "Envelopes from Linh", "creatorUniqueId": "linh.live", "scope": "creator", "gifterKey": null, "region": null, "eventTypes": [ "envelope" ], "minScore": null, "minRate": null, "minDiamondCount": 100, "minFollowerMilestone": null, "goodyBagAllowAllViewers": null, "goodyBagMaxRequiredLevel": null, "enabled": true, "createdAt": "2026-11-01T10:51:45.582Z", "updatedAt": "2026-11-01T10:51:45.582Z", "channels": [ { "id": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "target": null, "enabled": true, "hasSigningSecret": false } ] } ], "provenance": { "observedAt": "2026-11-01T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_rules", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-rules-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Create an alert rule
/v1/alerts/rulesA rule watches one creator (or a whole region) for event types and delivers to its channels. A webhook channel's signing secret is returned once, in webhookSecrets.
Request body
| Name | Type | Description |
|---|---|---|
nameRequired | string | Shown in notifications. |
creatorUniqueIdOptional | string | null | Watch one creator; omit for all of the region. |
scopeOptional | "creator" | "any" | "watchlist" | "gifter_watchlist" | What the rule watches: the pinned creator, every room (optionally one region), the creators on the workspace watchlist, or the gifter watchlist (one rule per workspace). Defaults to creator when creatorUniqueId is set, else any. |
regionOptional | string | null | |
eventTypesOptional | ("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[] | LIVE events (gift, envelope, goodyBag, live_start, live_end) and host checks run every hour for the rule's creator or watchlist: host_quiet (not LIVE for 3 days), league_change, diamond_target (a board day reached minDiamondCount) and follower_milestone (passed a multiple of minFollowerMilestone). |
minDiamondCountOptional | integer | null | Ignore events worth fewer diamonds. |
minFollowerMilestoneOptional | integer | null | Follower step for follower_milestone (e.g. 10000). |
enabledOptional | boolean | Default: true |
channelsOptional | object[] |
Request
curl -X POST "https://api.next.toktokdata.live/v1/alerts/rules" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Envelopes from Linh","creatorUniqueId":"linh.live","eventTypes":["envelope"],"minDiamondCount":100,"channels":[{"channelType":"webhook","target":"https://example.com/hooks/roomscope"}]}'Response
{ "rule": { "id": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "name": "Envelopes from Linh", "creatorUniqueId": "linh.live", "scope": "creator", "gifterKey": null, "region": null, "eventTypes": [ "envelope" ], "minScore": null, "minRate": null, "minDiamondCount": 100, "minFollowerMilestone": null, "goodyBagAllowAllViewers": null, "goodyBagMaxRequiredLevel": null, "enabled": true, "createdAt": "2026-11-01T10:51:45.582Z", "updatedAt": "2026-11-01T10:51:45.582Z", "channels": [ { "id": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "target": null, "enabled": true, "hasSigningSecret": false } ] }, "webhookSecrets": []}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Update an alert rule
/v1/alerts/rules/{rule_id}Send only the fields to change; channels replaces the whole list.
Path parameters
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | Alert rule id (UUID). |
Request body
| Name | Type | Description |
|---|---|---|
nameOptional | string | Shown in notifications. |
creatorUniqueIdOptional | string | null | Watch one creator; omit for all of the region. |
scopeOptional | "creator" | "any" | "watchlist" | "gifter_watchlist" | What the rule watches: the pinned creator, every room (optionally one region), the creators on the workspace watchlist, or the gifter watchlist (one rule per workspace). Defaults to creator when creatorUniqueId is set, else any. |
regionOptional | string | null | |
eventTypesOptional | ("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[] | LIVE events (gift, envelope, goodyBag, live_start, live_end) and host checks run every hour for the rule's creator or watchlist: host_quiet (not LIVE for 3 days), league_change, diamond_target (a board day reached minDiamondCount) and follower_milestone (passed a multiple of minFollowerMilestone). |
minDiamondCountOptional | integer | null | Ignore events worth fewer diamonds. |
minFollowerMilestoneOptional | integer | null | Follower step for follower_milestone (e.g. 10000). |
enabledOptional | boolean | Default: true |
channelsOptional | object[] |
Request
curl -X PATCH "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":false}'Response
{ "id": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "name": "Envelopes from Linh", "creatorUniqueId": "linh.live", "scope": "creator", "gifterKey": null, "region": null, "eventTypes": [ "envelope" ], "minScore": null, "minRate": null, "minDiamondCount": 100, "minFollowerMilestone": null, "goodyBagAllowAllViewers": null, "goodyBagMaxRequiredLevel": null, "enabled": true, "createdAt": "2026-11-01T10:51:45.582Z", "updatedAt": "2026-11-01T10:51:45.582Z", "channels": [ { "id": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "target": null, "enabled": true, "hasSigningSecret": false } ]}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Delete an alert rule
/v1/alerts/rules/{rule_id}Deletes the rule and its channels. Returns no body.
Path parameters
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | Alert rule id (UUID). |
Request
curl -X DELETE "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
204 with no body.
Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Send a test notification
/v1/alerts/rules/{rule_id}/testDelivers a synthetic event to every enabled channel of the rule now and returns how each went in results (delivered, failed or capped, with detail). Test fires and deliveries are logged with isTest: true.
Path parameters
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | Alert rule id (UUID). |
Request
curl -X POST "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9/test" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "enqueued": 2, "results": [ { "channelId": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "status": "delivered", "detail": null }, { "channelId": "9e1f2a3b-4c5d-5e6f-8a7b-0c1d2e3f4a5b", "channelType": "discord", "status": "failed", "detail": "discord HTTP 404" } ]}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Alert activity in the last 24 hours
/v1/alerts/statsEnabled rules, fires and deliveries by outcome over the last 24 hours (tests excluded).
Request
curl "https://api.next.toktokdata.live/v1/alerts/stats" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "rulesActive": 3, "fired24h": 41, "delivered24h": 78, "failed24h": 2, "capped24h": 0, "provenance": { "observedAt": "2026-11-06T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_history", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-history-v1", "window": { "from": "2026-11-05T10:00:00.000Z", "to": "2026-11-06T10:00:00.000Z", "label": "24h" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.