Organization API: Org Staff Alerts

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Organization API reference.

GET /api/v1/orgs/{org_slug}/staff/alerts/kinds

List what an alert can watch.

Each kind has a label, a description, the console page its figure comes from (source), the numbers it takes (params, each with a default, a range, the unit to show beside it and the phrase to read it in) and the lowest role that can read what it announces (min_role). Any member of the organization can read the list.

GET /api/v1/orgs/{org_slug}/staff/alerts/rules

List the organization's alert rules, newest first.

Each rule shows what it watches and its limits, where it goes, the last time it was checked and fired and the figure it read. The Discord address is never returned: discord_url_set says whether one is saved. Needs Tier 1 support or higher.

POST /api/v1/orgs/{org_slug}/staff/alerts/rules

Add an alert rule.

Pick a kind, its numbers (params) and where it goes (channels: in_app for the bell, email with recipients, discord with a discord_url). cooldown_minutes is the least time between two fires. An organization keeps up to 50 rules. Needs billing or higher.

application/json (required)

PATCH /api/v1/orgs/{org_slug}/staff/alerts/rules/{rule_id}

Change an alert rule. Send only what changes.

Changing the kind resets its params to the new kind's defaults unless you send them, and clears the last reading and the last fire. A discord_url replaces the saved one, and an empty value removes it. Needs billing or higher.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/staff/alerts/rules/{rule_id}

Delete an alert rule. The notifications it already raised stay in the bell.

They show to Tier 1 support and higher from then on, because the kind they came from is gone. Needs billing or higher.

POST /api/v1/orgs/{org_slug}/staff/alerts/rules/{rule_id}/test

Send a test of an alert rule to every channel it uses.

The test reads the figure now and sends it with the title starting "Test: ". It sends whether or not the alert is firing, and leaves the rule's cooldown and last fire alone. Answers { firing, value, sent, skipped, message }: sent lists the channels that took it and skipped the ones that did not, each with the reason. A test also shows in the bell, and is left out of digests. Ten tests an hour per person. Needs billing or higher.

GET /api/v1/orgs/{org_slug}/staff/notifications

List the alerts that fired, unread first, then newest first.

You see the alerts of the kinds your role can read. Each item is { id, title, body, severity, href, created_at, read, rule_id, rule_name }, with read being your own mark. unread is the bell's count (your unread alerts from the last 30 days) and total is how many notifications the filter matches. Any member of the organization can read them.

POST /api/v1/orgs/{org_slug}/staff/notifications/read

Mark notifications read for you: the ids you send, or all of them.

Marks are your own and nobody else sees them. An id you cannot read is ignored. Answers { marked, unread }. Any member of the organization can do this, read-only members included.

application/json (required)