Skip to content

Commit 67fc52d

Browse files
joeyorlandojoeyorlando
authored
add POST /escalation public API endpoint + add public API docs for teams/organization endpoints (#4815)
# What this PR does - Adds a `POST /escalation` public endpoint (equivalent to the internal direct paging API endpoint) - Adds public API documentation for teams and organization endpoints <img width="1140" alt="Screenshot 2024-08-15 at 12 49 40" src="https://github.com/user-attachments/assets/e0e8d6bb-f3ac-4f9e-bdf7-e8926949cc3b"> ## Which issue(s) this PR closes Closes grafana/oncall-private#2859 Closes #2448 ## 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.
1 parent 64bf1e5 commit 67fc52d

File tree

13 files changed

+752
-6
lines changed

13 files changed

+752
-6
lines changed

‎docs/sources/oncall-api-reference/escalation.md

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/escalation/
3+
title: Escalation HTTP API
4+
weight: 1200
5+
refs:
6+
users:
7+
- pattern: /docs/oncall/
8+
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/users
9+
- pattern: /docs/grafana-cloud/
10+
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/users
11+
teams:
12+
- pattern: /docs/oncall/
13+
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/teams
14+
- pattern: /docs/grafana-cloud/
15+
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/teams
16+
manual-paging:
17+
- pattern: /docs/oncall/
18+
destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/manual
19+
- pattern: /docs/grafana-cloud/
20+
destination: /docs/grafana-cloud/configure/integrations/references/manual
21+
---
22+
23+
# Escalation HTTP API
24+
25+
See [Manual paging integration](ref:manual-paging) for more background on how escalating to a team or user(s) works.
26+
27+
## Escalate to a set of users
28+
29+
For more details about how to fetch a user's Grafana OnCall ID, refer to the [Users](ref:users) public API documentation.
30+
31+
```shell
32+
curl "{{API_URL}}/api/v1/escalation/" \
33+
--request POST \
34+
--header "Authorization: meowmeowmeow" \
35+
--header "Content-Type: application/json" \
36+
--data '{
37+
"title": "We are seeing a network outage in the datacenter",
38+
"message": "I need help investigating, can you join the investigation?",
39+
"source_url": "https://github.com/myorg/myrepo/issues/123",
40+
"users": [
41+
{
42+
"id": "U281SN24AVVJX",
43+
"important": false
44+
},
45+
{
46+
"id": "U5AKCVNDEDUE7",
47+
"important": true
48+
}
49+
]
50+
}'
51+
```
52+
53+
The above command returns JSON structured in the following way:
54+
55+
```json
56+
{
57+
"id": "IZHCC4GTNPZ93",
58+
"integration_id": "CC3GZYZNIIEH5",
59+
"route_id": "RDN8LITALJXCJ",
60+
"alerts_count": 1,
61+
"state": "firing",
62+
"created_at": "2024-08-15T18:05:36.801215Z",
63+
"resolved_at": null,
64+
"resolved_by": null,
65+
"acknowledged_at": null,
66+
"acknowledged_by": null,
67+
"title": "We're seeing a network outage in the datacenter",
68+
"permalinks": {
69+
"slack": null,
70+
"slack_app": null,
71+
"telegram": null,
72+
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
73+
},
74+
"silenced_at": null
75+
}
76+
```
77+
78+
## Escalate to a team
79+
80+
For more details about how to fetch a team's Grafana OnCall ID, refer to the [Teams](ref:teams) public API documentation.
81+
82+
```shell
83+
curl "{{API_URL}}/api/v1/escalation/" \
84+
--request POST \
85+
--header "Authorization: meowmeowmeow" \
86+
--header "Content-Type: application/json" \
87+
--data '{
88+
"title": "We are seeing a network outage in the datacenter",
89+
"message": "I need help investigating, can you join the investigation?",
90+
"source_url": "https://github.com/myorg/myrepo/issues/123",
91+
"team": "TI73TDU19W48J"
92+
}'
93+
```
94+
95+
The above command returns JSON structured in the following way:
96+
97+
```json
98+
{
99+
"id": "IZHCC4GTNPZ93",
100+
"integration_id": "CC3GZYZNIIEH5",
101+
"route_id": "RDN8LITALJXCJ",
102+
"alerts_count": 1,
103+
"state": "firing",
104+
"created_at": "2024-08-15T18:05:36.801215Z",
105+
"resolved_at": null,
106+
"resolved_by": null,
107+
"acknowledged_at": null,
108+
"acknowledged_by": null,
109+
"title": "We're seeing a network outage in the datacenter",
110+
"permalinks": {
111+
"slack": null,
112+
"slack_app": null,
113+
"telegram": null,
114+
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
115+
},
116+
"silenced_at": null
117+
}
118+
```
119+
120+
## Escalate to a set of user(s) for an existing Alert Group
121+
122+
The following shows how you can escalate to a set of user(s) for an existing Alert Group.
123+
124+
```shell
125+
curl "{{API_URL}}/api/v1/escalation/" \
126+
--request POST \
127+
--header "Authorization: meowmeowmeow" \
128+
--header "Content-Type: application/json" \
129+
--data '{
130+
"alert_group_id": "IZMRNNY8RFS94",
131+
"users": [
132+
{
133+
"id": "U281SN24AVVJX",
134+
"important": false
135+
},
136+
{
137+
"id": "U5AKCVNDEDUE7",
138+
"important": true
139+
}
140+
]
141+
}'
142+
```
143+
144+
The above command returns JSON structured in the following way:
145+
146+
```json
147+
{
148+
"id": "IZHCC4GTNPZ93",
149+
"integration_id": "CC3GZYZNIIEH5",
150+
"route_id": "RDN8LITALJXCJ",
151+
"alerts_count": 1,
152+
"state": "firing",
153+
"created_at": "2024-08-15T18:05:36.801215Z",
154+
"resolved_at": null,
155+
"resolved_by": null,
156+
"acknowledged_at": null,
157+
"acknowledged_by": null,
158+
"title": "We're seeing a network outage in the datacenter",
159+
"permalinks": {
160+
"slack": null,
161+
"slack_app": null,
162+
"telegram": null,
163+
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
164+
},
165+
"silenced_at": null
166+
}
167+
```
168+
169+
| Parameter | Unique | Required | Description |
170+
| -------------------- | :----: | :--------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
171+
| `title` | No | No | Name of the Alert Group that will be created |
172+
| `message` | No | No | Content of the Alert Group that will be created |
173+
| `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. |
174+
| `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. |
175+
| `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. |
176+
| `alert_group_id` | No | No | If specified, will escalate the specified users for this Alert Group. |
177+
178+
## Things to note
179+
180+
- `team` and `users` are mutually exclusive in the request payload. If you would like to escalate to a team AND user(s),
181+
first escalate to a team, then using the Alert Group ID returned in the response payload, add the required users to the
182+
existing Alert Group
183+
- `alert_group_id` is mutually exclusive with `title`, `message`, and `source_url`. Practically speaking this means that
184+
if you are trying to escalate to a set of users on an existing Alert Group, you cannot update the `title`, `message`, or
185+
`source_url` of that Alert Group
186+
- If escalating to a set of users for an existing Alert Group, the Alert Group cannot be in a resolved state
187+
188+
**HTTP request**
189+
190+
`POST {{API_URL}}/api/v1/escalation/`

‎docs/sources/oncall-api-reference/organizations.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/organizations/
3+
title: Grafana OnCall organizations HTTP API
4+
weight: 1500
5+
refs:
6+
pagination:
7+
- pattern: /docs/oncall/
8+
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/#pagination
9+
- pattern: /docs/grafana-cloud/
10+
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/#pagination
11+
---
12+
13+
# Grafana OnCall organizations HTTP API
14+
15+
## Get an organization
16+
17+
This endpoint retrieves the organization object.
18+
19+
```shell
20+
curl "{{API_URL}}/api/v1/organizations/O53AAGWFBPE5W/" \
21+
--request GET \
22+
--header "Authorization: meowmeowmeow" \
23+
--header "Content-Type: application/json"
24+
````
25+
26+
The above command returns JSON structured in the following way:
27+
28+
```json
29+
{
30+
"id": "O53AAGWFBPE5W"
31+
}
32+
```
33+
34+
**HTTP request**
35+
36+
`GET {{API_URL}}/api/v1/organizations/<ORGANIZATION_ID>/`
37+
38+
| Parameter | Unique | Description |
39+
| ---------- | :-----: | :----------------------------------------------------------------- |
40+
| `id` | Yes | Organization ID |
41+
42+
## List Organizations
43+
44+
```shell
45+
curl "{{API_URL}}/api/v1/organizations/" \
46+
--request GET \
47+
--header "Authorization: meowmeowmeow" \
48+
--header "Content-Type: application/json"
49+
```
50+
51+
The above command returns JSON structured in the following way:
52+
53+
```json
54+
{
55+
"count": 1,
56+
"next": null,
57+
"previous": null,
58+
"results": [
59+
{
60+
"id": "O53AAGWFBPE5W"
61+
}
62+
],
63+
"page_size": 25,
64+
"current_page_number": 1,
65+
"total_pages": 1
66+
}
67+
```
68+
69+
> **Note**: The response is [paginated](ref:pagination). You may need to make multiple requests to get all records.
70+
71+
**HTTP request**
72+
73+
`GET {{API_URL}}/api/v1/organizations/`

‎docs/sources/oncall-api-reference/teams.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/teams/
3+
title: Grafana OnCall teams HTTP API
4+
weight: 1500
5+
refs:
6+
pagination:
7+
- pattern: /docs/oncall/
8+
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/#pagination
9+
- pattern: /docs/grafana-cloud/
10+
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/#pagination
11+
---
12+
13+
# Grafana OnCall teams HTTP API
14+
15+
## Get a team
16+
17+
This endpoint retrieves the team object.
18+
19+
```shell
20+
curl "{{API_URL}}/api/v1/teams/TI73TDU19W48J/" \
21+
--request GET \
22+
--header "Authorization: meowmeowmeow" \
23+
--header "Content-Type: application/json"
24+
````
25+
26+
The above command returns JSON structured in the following way:
27+
28+
```json
29+
{
30+
"id": "TI73TDU19W48J",
31+
"name": "my test team",
32+
"email": "",
33+
"avatar_url": "/avatar/3f49c15916554246daa714b9bd0ee398"
34+
}
35+
```
36+
37+
**HTTP request**
38+
39+
`GET {{API_URL}}/api/v1/teams/<TEAM_ID>/`
40+
41+
| Parameter | Unique | Description |
42+
| ---------- | :-----: | :----------------------------------------------------------------- |
43+
| `id` | Yes/org | Team ID |
44+
| `name` | Yes/org | Team name |
45+
| `email` | Yes/org | Team e-mail |
46+
| `avatar_url` | Yes | Avatar URL of the Grafana team |
47+
48+
## List Teams
49+
50+
```shell
51+
curl "{{API_URL}}/api/v1/teams/" \
52+
--request GET \
53+
--header "Authorization: meowmeowmeow" \
54+
--header "Content-Type: application/json"
55+
```
56+
57+
The above command returns JSON structured in the following way:
58+
59+
```json
60+
{
61+
"count": 1,
62+
"next": null,
63+
"previous": null,
64+
"results": [
65+
{
66+
"id": "TI73TDU19W48J",
67+
"name": "my test team",
68+
"email": "",
69+
"avatar_url": "/avatar/3f49c15916554246daa714b9bd0ee398"
70+
}
71+
],
72+
"page_size": 50,
73+
"current_page_number": 1,
74+
"total_pages": 1
75+
}
76+
```
77+
78+
> **Note**: The response is [paginated](ref:pagination). You may need to make multiple requests to get all records.
79+
80+
The following available filter parameter should be provided as a `GET` argument:
81+
82+
- `name` (Exact match)
83+
84+
**HTTP request**
85+
86+
`GET {{API_URL}}/api/v1/teams/`

0 commit comments

Comments
 (0)