Stackurity Start free trial

API reference Notifications

Notifications

39 operations. Base URL https://app.stackurity.dev/api/v1 on Stackurity Cloud; see authentication.

A asset's notifications

GET /assets/{id}/notifications

Role: security on the asset

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add a channel of the asset

POST /assets/{id}/notifications/channels

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a channel of the asset

PATCH /assets/{id}/notifications/channels/{cid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
cid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a channel of the asset

DELETE /assets/{id}/notifications/channels/{cid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
cid requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Test a channel of the asset

POST /assets/{id}/notifications/channels/{cid}/test

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
cid requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Turn an inherited rule on, off, or edit it for the asset

PUT /assets/{id}/notifications/inherited/{rid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
rid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add a rule of the asset

POST /assets/{id}/notifications/routes

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a rule of the asset

PUT /assets/{id}/notifications/routes/{rid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
rid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a rule of the asset

DELETE /assets/{id}/notifications/routes/{rid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
rid requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Notification channels

GET /channels

Role: security

Notification configuration and delivery log

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a notification channel

POST /channels

Role: admin

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a notification channel

PATCH /channels/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a notification channel

DELETE /channels/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Send a test message (Jira, ServiceNow: check access only)

POST /channels/{id}/test

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Notification delivery log

GET /deliveries

Role: security

Notification configuration and delivery log

Parameters

ParameterInTypeDescription
statusquerystring
incident_idquerystring
channel_idquerystringOne channel
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Retry a failed or held delivery

POST /deliveries/{id}/retry

Role: admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Addresses that email sent by Stackurity may reach

GET /email-recipients

Role: security

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Never email this address again

POST /email-recipients/block

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Confirm an address for email sent by Stackurity

POST /email-recipients/confirm

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Send a confirmation link again

POST /email-recipients/resend

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Stop email sent by Stackurity to an address

POST /email/unsubscribe

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

What notifications this server offers

GET /notification-options

Role: security

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

A project's notifications

GET /projects/{id}/notifications

Role: security on the project

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add a channel of the project

POST /projects/{id}/notifications/channels

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a channel of the project

PATCH /projects/{id}/notifications/channels/{cid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
cid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a channel of the project

DELETE /projects/{id}/notifications/channels/{cid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
cid requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Test a channel of the project

POST /projects/{id}/notifications/channels/{cid}/test

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
cid requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Turn an inherited rule on, off, or edit it for the project

PUT /projects/{id}/notifications/inherited/{rid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
rid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add a rule of the project

POST /projects/{id}/notifications/routes

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a rule of the project

PUT /projects/{id}/notifications/routes/{rid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
rid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a rule of the project

DELETE /projects/{id}/notifications/routes/{rid}

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring
rid requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Add to Slack for a project

POST /projects/{id}/notifications/slack/install

Role: admin of the project or asset

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add to Teams for a project

POST /projects/{id}/notifications/teams/install

Role: admin of the project or asset

Starts Add to Teams for a channel of the project; as Add to Slack for a project.

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Notification routes

GET /routes

Role: security

Notification configuration and delivery log

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a notification route

POST /routes

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Replace a notification route

PUT /routes/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a notification route

DELETE /routes/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Notification settings of the organisation

GET /settings/notifications

Role: security

project_chat_apps: whether project admins may connect their own Slack or Teams workspace (default false).

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change notification settings

PUT /settings/notifications

Role: admin

Sets project_chat_apps; audited as settings.notifications.

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError