# Organization API: Org Staff Alerts

> Every Organization API operation tagged Org Staff Alerts.

Source: https://www.coritan.com/docs/api/reference/organizations/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](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/staff/alerts/kinds`](#op-get-api-v1-orgs-org-slug-staff-alerts-kinds) | List what an alert can watch |
| GET | [`/api/v1/orgs/{org_slug}/staff/alerts/rules`](#op-get-api-v1-orgs-org-slug-staff-alerts-rules) | List the organization's alert rules, newest first |
| POST | [`/api/v1/orgs/{org_slug}/staff/alerts/rules`](#op-post-api-v1-orgs-org-slug-staff-alerts-rules) | Add an alert rule |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/alerts/rules/{rule_id}`](#op-patch-api-v1-orgs-org-slug-staff-alerts-rules-rule-id) | Change an alert rule |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/alerts/rules/{rule_id}`](#op-delete-api-v1-orgs-org-slug-staff-alerts-rules-rule-id) | Delete an alert rule |
| POST | [`/api/v1/orgs/{org_slug}/staff/alerts/rules/{rule_id}/test`](#op-post-api-v1-orgs-org-slug-staff-alerts-rules-rule-id-test) | Send a test of an alert rule to every channel it uses |
| GET | [`/api/v1/orgs/{org_slug}/staff/notifications`](#op-get-api-v1-orgs-org-slug-staff-notifications) | List the alerts that fired, unread first, then newest first |
| POST | [`/api/v1/orgs/{org_slug}/staff/notifications/read`](#op-post-api-v1-orgs-org-slug-staff-notifications-read) | Mark notifications read for you: the ids you send, or all of them |

### List what an alert can watch {#op-get-api-v1-orgs-org-slug-staff-alerts-kinds}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List the organization's alert rules, newest first {#op-get-api-v1-orgs-org-slug-staff-alerts-rules}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add an alert rule {#op-post-api-v1-orgs-org-slug-staff-alerts-rules}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | What the alert is called in the list. |
| `kind` | string | yes | What it watches: tickets_past_sla, oldest_ticket_wait, refunds_waiting, invoices_overdue, disputes_open, orders_stuck, servers_attention, abuse_patterns_new, no_orders, payment_failures, chat_reports_open. |
| `params` | object or null | no | The numbers the kind takes (see `GET staff/alerts/kinds`). Left out, the defaults. |
| `channels` | array of string | no | Where it goes: some of in_app, email, discord. Web push is each member's own setting. |
| `recipients` | array of string | no | Up to 20 email addresses for the `email` channel. |
| `discord_url` | string or null | no | A Discord webhook address for the `discord` channel. Never shown again. |
| `cooldown_minutes` | integer | no | The least time between two fires of this alert, 5 minutes to 7 days. |
| `enabled` | boolean | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change an alert rule {#op-patch-api-v1-orgs-org-slug-staff-alerts-rules-rule-id}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `rule_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `kind` | string or null | no |
| `params` | object or null | no |
| `channels` | array of string or null | no |
| `recipients` | array of string or null | no |
| `discord_url` | string or null | no |
| `cooldown_minutes` | integer or null | no |
| `enabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete an alert rule {#op-delete-api-v1-orgs-org-slug-staff-alerts-rules-rule-id}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `rule_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send a test of an alert rule to every channel it uses {#op-post-api-v1-orgs-org-slug-staff-alerts-rules-rule-id-test}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `rule_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List the alerts that fired, unread first, then newest first {#op-get-api-v1-orgs-org-slug-staff-notifications}

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `unread_only` | query | boolean | no | Only the notifications you have not read. Default: `False`. |
| `limit` | query | integer | no | Notifications per page, 1 to 200. Default: `50`. |
| `offset` | query | integer | no | How many notifications to skip, for the next page. Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mark notifications read for you: the ids you send, or all of them {#op-post-api-v1-orgs-org-slug-staff-notifications-read}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ids` | array of integer or null | no | The notifications to mark read. |
| `all` | boolean | no | Mark every notification you can read as read. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |