152d5f74fc
## Which issue(s) this PR closes https://www.loom.com/share/e1858db48e8b4fa99014a997af5e3d5e Closes https://github.com/grafana/irm/issues/322 ## Checklist - [x] Unit, integration, and e2e (if applicable) tests updated - [x] Documentation added (or `pr:no public docs` PR label added if not required) - [x] Added the relevant release notes label (see labels prefixed w/ `release:`). These labels dictate how your PR will show up in the autogenerated release notes. --------- Co-authored-by: Vadim Stepanov <vadimkerr@gmail.com>
203 lines
9 KiB
Markdown
203 lines
9 KiB
Markdown
---
|
|
canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/escalation/
|
|
title: Escalation HTTP API
|
|
weight: 0
|
|
refs:
|
|
users:
|
|
- pattern: /docs/oncall/
|
|
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/users
|
|
- pattern: /docs/grafana-cloud/
|
|
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/users
|
|
teams:
|
|
- pattern: /docs/oncall/
|
|
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/teams
|
|
- pattern: /docs/grafana-cloud/
|
|
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/teams
|
|
manual-paging:
|
|
- pattern: /docs/oncall/
|
|
destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/manual
|
|
- pattern: /docs/grafana-cloud/
|
|
destination: /docs/grafana-cloud/configure/integrations/references/manual
|
|
manual-paging-team-important:
|
|
- pattern: /docs/oncall/
|
|
destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/manual#important-escalations
|
|
- pattern: /docs/grafana-cloud/
|
|
destination: /docs/grafana-cloud/configure/integrations/references/manual#important-escalations
|
|
---
|
|
|
|
# Escalation HTTP API
|
|
|
|
**Required permission**: `grafana-oncall-app.alert-groups:direct-paging` (user authentication only)
|
|
|
|
See [Manual paging integration](ref:manual-paging) for more background on how escalating to a team or user(s) works.
|
|
|
|
## Escalate to a set of users
|
|
|
|
For more details about how to fetch a user's Grafana OnCall ID, refer to the [Users](ref:users) public API documentation.
|
|
|
|
```shell
|
|
curl "{{API_URL}}/api/v1/escalation/" \
|
|
--request POST \
|
|
--header "Authorization: meowmeowmeow" \
|
|
--header "Content-Type: application/json" \
|
|
--data '{
|
|
"title": "We are seeing a network outage in the datacenter",
|
|
"message": "I need help investigating, can you join the investigation?",
|
|
"source_url": "https://github.com/myorg/myrepo/issues/123",
|
|
"users": [
|
|
{
|
|
"id": "U281SN24AVVJX",
|
|
"important": false
|
|
},
|
|
{
|
|
"id": "U5AKCVNDEDUE7",
|
|
"important": true
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
The above command returns JSON structured in the following way:
|
|
|
|
```json
|
|
{
|
|
"id": "IZHCC4GTNPZ93",
|
|
"integration_id": "CC3GZYZNIIEH5",
|
|
"route_id": "RDN8LITALJXCJ",
|
|
"alerts_count": 1,
|
|
"state": "firing",
|
|
"created_at": "2024-08-15T18:05:36.801215Z",
|
|
"resolved_at": null,
|
|
"resolved_by": null,
|
|
"acknowledged_at": null,
|
|
"acknowledged_by": null,
|
|
"title": "We're seeing a network outage in the datacenter",
|
|
"permalinks": {
|
|
"slack": null,
|
|
"slack_app": null,
|
|
"telegram": null,
|
|
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
|
|
},
|
|
"silenced_at": null
|
|
}
|
|
```
|
|
|
|
## Escalate to a team
|
|
|
|
For more details about how to fetch a team's Grafana OnCall ID, refer to the [Teams](ref:teams) public API documentation.
|
|
|
|
```shell
|
|
curl "{{API_URL}}/api/v1/escalation/" \
|
|
--request POST \
|
|
--header "Authorization: meowmeowmeow" \
|
|
--header "Content-Type: application/json" \
|
|
--data '{
|
|
"title": "We are seeing a network outage in the datacenter",
|
|
"message": "I need help investigating, can you join the investigation?",
|
|
"source_url": "https://github.com/myorg/myrepo/issues/123",
|
|
"team": "TI73TDU19W48J",
|
|
"important_team_escalation": true
|
|
}'
|
|
```
|
|
|
|
The above command returns JSON structured in the following way:
|
|
|
|
```json
|
|
{
|
|
"id": "IZHCC4GTNPZ93",
|
|
"integration_id": "CC3GZYZNIIEH5",
|
|
"route_id": "RDN8LITALJXCJ",
|
|
"alerts_count": 1,
|
|
"state": "firing",
|
|
"created_at": "2024-08-15T18:05:36.801215Z",
|
|
"resolved_at": null,
|
|
"resolved_by": null,
|
|
"acknowledged_at": null,
|
|
"acknowledged_by": null,
|
|
"title": "We're seeing a network outage in the datacenter",
|
|
"permalinks": {
|
|
"slack": null,
|
|
"slack_app": null,
|
|
"telegram": null,
|
|
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
|
|
},
|
|
"silenced_at": null
|
|
}
|
|
```
|
|
|
|
## Escalate to a set of user(s) for an existing Alert Group
|
|
|
|
The following shows how you can escalate to a set of user(s) for an existing Alert Group.
|
|
|
|
```shell
|
|
curl "{{API_URL}}/api/v1/escalation/" \
|
|
--request POST \
|
|
--header "Authorization: meowmeowmeow" \
|
|
--header "Content-Type: application/json" \
|
|
--data '{
|
|
"alert_group_id": "IZMRNNY8RFS94",
|
|
"users": [
|
|
{
|
|
"id": "U281SN24AVVJX",
|
|
"important": false
|
|
},
|
|
{
|
|
"id": "U5AKCVNDEDUE7",
|
|
"important": true
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
The above command returns JSON structured in the following way:
|
|
|
|
```json
|
|
{
|
|
"id": "IZHCC4GTNPZ93",
|
|
"integration_id": "CC3GZYZNIIEH5",
|
|
"route_id": "RDN8LITALJXCJ",
|
|
"alerts_count": 1,
|
|
"state": "firing",
|
|
"created_at": "2024-08-15T18:05:36.801215Z",
|
|
"resolved_at": null,
|
|
"resolved_by": null,
|
|
"acknowledged_at": null,
|
|
"acknowledged_by": null,
|
|
"title": "We're seeing a network outage in the datacenter",
|
|
"permalinks": {
|
|
"slack": null,
|
|
"slack_app": null,
|
|
"telegram": null,
|
|
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
|
|
},
|
|
"silenced_at": null
|
|
}
|
|
```
|
|
|
|
| Parameter | Unique | Required | Description |
|
|
| -------------------- | :----: | :--------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `title` | No | No | Name of the Alert Group that will be created |
|
|
| `message` | No | No | Content of the Alert Group that will be created |
|
|
| `source_url` | No | No | Value that will be added in the Alert's payload as `oncall.permalink`. This can be useful to have the source URL/button autopopulated with a URL of interest. |
|
|
| `team` | No | Yes (see [Things to Note](#things-to-note)) | Grafana OnCall team ID. If specified, will use the "Direct Paging" Integration associated with this Grafana OnCall team, to create the Alert Group. |
|
|
| `users` | No | Yes (see [Things to Note](#things-to-note)) | List of user(s) to escalate to. See above request example for object schema. `id` represents the Grafana OnCall user's ID. `important` is a boolean representing whether to escalate the Alert Group using this user's default or important personal notification policy. |
|
|
| `alert_group_id` | No | No | If specified, will escalate the specified users for this Alert Group. |
|
|
| `important_team_escalation` | No | No | Sets the value of `payload.oncall.important` to the value specified here (default is `False`; see [Things to Note](#things-to-note) for more details). |
|
|
|
|
## Things to note
|
|
|
|
- `team` and `users` are mutually exclusive in the request payload. If you would like to escalate to a team AND user(s),
|
|
first escalate to a team, then using the Alert Group ID returned in the response payload, add the required users to the
|
|
existing Alert Group
|
|
- `alert_group_id` is mutually exclusive with `title`, `message`, and `source_url`. Practically speaking this means that
|
|
if you are trying to escalate to a set of users on an existing Alert Group, you cannot update the `title`, `message`, or
|
|
`source_url` of that Alert Group
|
|
- If escalating to a set of users for an existing Alert Group, the Alert Group cannot be in a resolved state
|
|
- Regarding `important_team_escalation`; this can be useful to send an "important" escalation to the specified team.
|
|
Teams can configure their Direct Paging Integration to route to different escalation chains based on the value of
|
|
`payload.oncall.important`. See [Manual paging integration - important escalations](ref:manual-paging-team-important)
|
|
for more details.
|
|
|
|
**HTTP request**
|
|
|
|
`POST {{API_URL}}/api/v1/escalation/`
|