RoomScope

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

GET/v1/alerts/deliveries

One 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.

Scopewebhook:manageCreditsFree

Query parameters

Query parameters · GET /v1/alerts/deliveries
NameTypeDescription
ruleIdOptional
stringOnly this rule (UUID).
statusOptional
"delivered" | "failed" | "capped"Only this outcome.
sinceOptional
stringISO 8601 time; only newer rows.
limitOptional
integerRows to return. Range 1–200.
Default: 50

Request

curl "https://api.next.toktokdata.live/v1/alerts/deliveries" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

List alert fires

GET/v1/alerts/fires

Every time a rule matched an event, newest first, whether or not a channel delivered it (compare with deliveries).

Scopewebhook:manageCreditsFree

Query parameters

Query parameters · GET /v1/alerts/fires
NameTypeDescription
ruleIdOptional
stringOnly this rule (UUID).
sinceOptional
stringISO 8601 time; only newer rows.
limitOptional
integerRows to return. Range 1–200.
Default: 50

Request

curl "https://api.next.toktokdata.live/v1/alerts/fires" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

List alert rules

GET/v1/alerts/rules

Every rule of the workspace with its channels. Signing secrets are never returned again.

Scopewebhook:manageCreditsFree

Request

curl "https://api.next.toktokdata.live/v1/alerts/rules" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Create an alert rule

POST/v1/alerts/rules

A 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.

Scopewebhook:manageCreditsFree

Request body

Request body · POST /v1/alerts/rules
NameTypeDescription
nameRequired
stringShown in notifications.
creatorUniqueIdOptional
string | nullWatch 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 | nullIgnore events worth fewer diamonds.
minFollowerMilestoneOptional
integer | nullFollower 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

201 Created
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Update an alert rule

PATCH/v1/alerts/rules/{rule_id}

Send only the fields to change; channels replaces the whole list.

Scopewebhook:manageCreditsFree

Path parameters

Path parameters · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringAlert rule id (UUID).

Request body

Request body · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
nameOptional
stringShown in notifications.
creatorUniqueIdOptional
string | nullWatch 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 | nullIgnore events worth fewer diamonds.
minFollowerMilestoneOptional
integer | nullFollower 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

200 OK
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Delete an alert rule

DELETE/v1/alerts/rules/{rule_id}

Deletes the rule and its channels. Returns no body.

Scopewebhook:manageCreditsFree

Path parameters

Path parameters · DELETE /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringAlert 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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Send a test notification

POST/v1/alerts/rules/{rule_id}/test

Delivers 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.

Scopewebhook:manageCreditsFree

Path parameters

Path parameters · POST /v1/alerts/rules/{rule_id}/test
NameTypeDescription
rule_idRequired
stringAlert 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

200 OK
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Alert activity in the last 24 hours

GET/v1/alerts/stats

Enabled rules, fires and deliveries by outcome over the last 24 hours (tests excluded).

Scopewebhook:manageCreditsFree

Request

curl "https://api.next.toktokdata.live/v1/alerts/stats" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.
Was this page helpful?