API reference Notifications
Notifications
A asset's notifications
GET /assets/{id}/notifications
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Answer: inherited (each with state on, off or edited and copy_id), routes, channels, usable_channels, project_chat_apps, org_admins.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Add a channel of the asset
POST /assets/{id}/notifications/channels
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Fields as POST /channels. Without an organisation-wide admin role, only email sent by Stackurity.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Change a channel of the asset
PATCH /assets/{id}/notifications/channels/{cid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
cid required | path | string |
Request body
application/json, required: object
Responses
Delete a channel of the asset
DELETE /assets/{id}/notifications/channels/{cid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
cid required | path | string |
Responses
Test a channel of the asset
POST /assets/{id}/notifications/channels/{cid}/test
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
cid required | path | string |
Responses
Turn an inherited rule on, off, or edit it for the asset
PUT /assets/{id}/notifications/inherited/{rid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. state: off (turned off here), on (applies again; an edited copy is deleted) or edit (the asset gets its own copy to change, and the inherited rule is turned off here).
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
rid required | path | string |
Request body
application/json, required: object
Responses
Add a rule of the asset
POST /assets/{id}/notifications/routes
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Fields as POST /routes; the rule belongs to the asset. It sends to the organisation's channels or the asset's own.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Change a rule of the asset
PUT /assets/{id}/notifications/routes/{rid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
rid required | path | string |
Request body
application/json, required: object
Responses
Delete a rule of the asset
DELETE /assets/{id}/notifications/routes/{rid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Deleting an edited copy of an inherited rule turns the inherited rule on again here.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
rid required | path | string |
Responses
Notification channels
GET /channels
Notification configuration and delivery log
Responses
Create a notification channel
POST /channels
Request body
application/json, required: object
Responses
Change a notification channel
PATCH /channels/{id}
Email, Slack, Teams, webhook, Jira, PagerDuty (pagerduty, Events API v2) and ServiceNow (servicenow, Table API) channels. Jira, PagerDuty and ServiceNow keep one record per incident. Test: Jira and ServiceNow check access without creating anything; PagerDuty triggers a test alert (severity info) and resolves it at once
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Delete a notification channel
DELETE /channels/{id}
Email, Slack, Teams, webhook, Jira, PagerDuty (pagerduty, Events API v2) and ServiceNow (servicenow, Table API) channels. Jira, PagerDuty and ServiceNow keep one record per incident. Test: Jira and ServiceNow check access without creating anything; PagerDuty triggers a test alert (severity info) and resolves it at once
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Send a test message (Jira, ServiceNow: check access only)
POST /channels/{id}/test
Email, Slack, Teams, webhook, Jira, PagerDuty (pagerduty, Events API v2) and ServiceNow (servicenow, Table API) channels. Jira, PagerDuty and ServiceNow keep one record per incident. Test: Jira and ServiceNow check access without creating anything; PagerDuty triggers a test alert (severity info) and resolves it at once
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Notification delivery log
GET /deliveries
Notification configuration and delivery log
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
status | query | string | |
incident_id | query | string | |
channel_id | query | string | One channel |
limit | query | string | Page size (default 100, at most 500) |
offset | query | string | Items to skip |
Responses
Retry a failed or held delivery
POST /deliveries/{id}/retry
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Addresses that email sent by Stackurity may reach
GET /email-recipients
Addresses named by stackurity_email channels that are not members: email, status (pending until the address clicks the confirmation link, then confirmed), requested_at, confirmed_at
Responses
Never email this address again
POST /email-recipients/block
{"token"} from a confirmation email's "Never email me again" link (/email/block#emc_...): the address is blocked for every organisation on the server and its pending requests removed. Answers email; 410 link_invalid
Request body
application/json, required: object
Responses
Confirm an address for email sent by Stackurity
POST /email-recipients/confirm
{"token"} from the emailed link (/email/confirm#emc_...). Answers email and organisation; 410 link_invalid when the link is unknown, used or expired (7 days)
Request body
application/json, required: object
Responses
Send a confirmation link again
POST /email-recipients/resend
{"email"} of a pending address. 202; 429 too_soon when one was sent in the last 10 minutes; 404 for an unknown or confirmed address
Request body
application/json, required: object
Responses
Stop email sent by Stackurity to an address
POST /email/unsubscribe
{"token"} from an email's "Stop these emails" link (/email/unsubscribe#...), signed for one organisation and address: the address is taken out of that organisation's stackurity_email channels. Answers email and organisation; 410 link_invalid. Mail clients use the one-click address in the List-Unsubscribe header (RFC 8058), POST /email/unsubscribe/one-click?t=..., outside /api/v1
Request body
application/json, required: object
Responses
What notifications this server offers
GET /notification-options
slack_app (Add to Slack is configured), platform_email (enabled; when enabled also from, max_recipients and quota with per_minute, per_hour, per_day: email sent by Stackurity), secrets (stored secrets work) and base_url (STACKURITY_BASE_URL is set)
Responses
A project's notifications
GET /projects/{id}/notifications
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Answer: inherited (each with state on, off or edited and copy_id), routes, channels, usable_channels, project_chat_apps, org_admins.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Add a channel of the project
POST /projects/{id}/notifications/channels
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Fields as POST /channels. Without an organisation-wide admin role, only email sent by Stackurity.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Change a channel of the project
PATCH /projects/{id}/notifications/channels/{cid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
cid required | path | string |
Request body
application/json, required: object
Responses
Delete a channel of the project
DELETE /projects/{id}/notifications/channels/{cid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
cid required | path | string |
Responses
Test a channel of the project
POST /projects/{id}/notifications/channels/{cid}/test
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
cid required | path | string |
Responses
Turn an inherited rule on, off, or edit it for the project
PUT /projects/{id}/notifications/inherited/{rid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. state: off (turned off here), on (applies again; an edited copy is deleted) or edit (the project gets its own copy to change, and the inherited rule is turned off here).
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
rid required | path | string |
Request body
application/json, required: object
Responses
Add a rule of the project
POST /projects/{id}/notifications/routes
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Fields as POST /routes; the rule belongs to the project. It sends to the organisation's channels or the project's own.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Change a rule of the project
PUT /projects/{id}/notifications/routes/{rid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
rid required | path | string |
Request body
application/json, required: object
Responses
Delete a rule of the project
DELETE /projects/{id}/notifications/routes/{rid}
The project's (or asset's) notifications: rules inherited from the organisation (and, for an asset, from its projects), its own rules and channels. Security on the project or asset reads; admin on it (an organisation-wide admin, or an admin grant) changes. Deleting an edited copy of an inherited rule turns the inherited rule on again here.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
rid required | path | string |
Responses
Add to Slack for a project
POST /projects/{id}/notifications/slack/install
Starts Add to Slack for a channel of the project. Needs the admin role on the project and, without an organisation-wide admin role, the organisation's project_chat_apps setting (403 otherwise).
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Add to Teams for a project
POST /projects/{id}/notifications/teams/install
Starts Add to Teams for a channel of the project; as Add to Slack for a project.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Notification routes
GET /routes
Notification configuration and delivery log
Responses
Create a notification route
POST /routes
Which incidents go to which channel. project_ids limits a route to those projects' assets: its messages count and name only them, and only their collection and coverage problems. For a Jira channel, at most one project (400 otherwise): its issues then describe only that project's part of each incident, see Incidents and notifications. A route to a PagerDuty or ServiceNow channel cannot name projects (400). events: any of urgent, new_issues, regressed, overdue, connected, problems, daily_summary, weekly_summary; event_channels (Slack only) sends some events to other Slack channels; new_min_priority is the threshold of new_issues; summary_updates (default false) adds an Updates available section to the route's weekly summary (never the daily one). mode (urgent_summary, urgent_weekly, urgent_only, daily, weekly) is still accepted and translated to events; returned as one of them or custom
Request body
application/json, required: object
Responses
Replace a notification route
PUT /routes/{id}
Which incidents go to which channel. project_ids limits a route to those projects' assets: its messages count and name only them, and only their collection and coverage problems. For a Jira channel, at most one project (400 otherwise): its issues then describe only that project's part of each incident, see Incidents and notifications. A route to a PagerDuty or ServiceNow channel cannot name projects (400). events: any of urgent, new_issues, regressed, overdue, connected, problems, daily_summary, weekly_summary; event_channels (Slack only) sends some events to other Slack channels; new_min_priority is the threshold of new_issues; summary_updates (default false) adds an Updates available section to the route's weekly summary (never the daily one). mode (urgent_summary, urgent_weekly, urgent_only, daily, weekly) is still accepted and translated to events; returned as one of them or custom
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Delete a notification route
DELETE /routes/{id}
Which incidents go to which channel. project_ids limits a route to those projects' assets: its messages count and name only them, and only their collection and coverage problems. For a Jira channel, at most one project (400 otherwise): its issues then describe only that project's part of each incident, see Incidents and notifications. A route to a PagerDuty or ServiceNow channel cannot name projects (400). mode: urgent_summary, urgent_only, daily, weekly
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Notification settings of the organisation
GET /settings/notifications
project_chat_apps: whether project admins may connect their own Slack or Teams workspace (default false).
Responses
Change notification settings
PUT /settings/notifications
Sets project_chat_apps; audited as settings.notifications.
Request body
application/json, required: object