OnCall shifts HTTP API

Create an OnCall shift

Required permission: grafana-oncall-app.schedules:write

curl "{{API_URL}}/api/v1/on_call_shifts/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "Demo single event",
      "type": "single_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T08:00:00",
      "duration": 10800,
      "users": [
          "U4DNY931HHJS5"
      ]
  }'

The above command returns JSON structured in the following way:

{
  "id": "OH3V5FYQEYJ6M",
  "name": "Demo single event",
  "type": "single_event",
  "team_id": null,
  "time_zone": null,
  "level": 0,
  "start": "2020-09-10T08:00:00",
  "duration": 10800,
  "users": ["U4DNY931HHJS5"]
}

Parameter	Unique	Required	Description
`name`	Yes	Yes	On-call shift name.
`type`	No	Yes	One of: `single_event`, `recurrent_event`, `rolling_users`.
`team_id`	No	ID of the team.
`time_zone`	No	Optional	On-call shift time zone. Default is local schedule time zone. This field will override the schedule time zone if changed. For more information refer to time zones.
`level`	No	Optional	Priority level. The higher the value, the higher the priority. If two events overlap in one schedule, Grafana OnCall will choose the event with higher level. For example: Alex is on-call from 8AM till 11AM with level 1, Bob is on-call from 9AM till 11AM with level 2. At 10AM Grafana OnCall will notify Bob. At 8AM OnCall will notify Alex.
`start`	No	Yes	Start time of the on-call shift. This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example “2020-09-05T08:00:00”).
`duration`	No	Yes	Duration of the event.
`frequency`	No	If type = `recurrent_event` or `rolling_users`	One of: `hourly`, `daily`, `weekly`, `monthly`.
`interval`	No	Optional	This parameter takes a positive integer that represents the intervals that the recurrence rule repeats. If `frequency` is set, the default assumed value for this will be `1`.
`until`	No	Optional	When the recurrence rule ends (endless if None). This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example “2020-09-05T08:00:00”).
`week_start`	No	Optional	Start day of the week in iCal format. One of: `SU` (Sunday), `MO` (Monday), `TU` (Tuesday), `WE` (Wednesday), `TH` (Thursday), `FR` (Friday), `SA` (Saturday). Default: `SU`.
`by_day`	No	Optional	List of days in iCal format. Valid values are: `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA`.
`by_month`	No	Optional	List of months. Valid values are `1` to `12`.
`by_monthday`	No	Optional	List of days of the month. Valid values are `1` to `31` or `-31` to `-1`.
`users`	No	Optional	List of on-call users.
`rolling_users`	No	Optional	List of lists with on-call users (for `rolling_users` event type). Grafana OnCall will iterate over lists of users for every time frame specified in `frequency`. For example: there are two lists of users in `rolling_users` : [[Alex, Bob], [Alice]] and `frequency` = `daily` . This means that the first day Alex and Bob will be notified. The next day: Alice. The day after: Alex and Bob again and so on.
`start_rotation_from_user_index`	No	Optional	Index of the list of users in `rolling_users`, from which on-call rotation starts. By default, the start index is `0`

For more information about recurrence rules, refer to RFC 5545.

HTTP request

POST {{API_URL}}/api/v1/on_call_shifts/

Get OnCall shifts

Required permission: grafana-oncall-app.schedules:read

curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

{
  "id": "OH3V5FYQEYJ6M",
  "name": "Demo single event",
  "type": "single_event",
  "team_id": null,
  "time_zone": null,
  "level": 0,
  "start": "2020-09-10T08:00:00",
  "duration": 10800,
  "users": ["U4DNY931HHJS5"]
}

HTTP request

GET {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

List OnCall shifts

Required permission: grafana-oncall-app.schedules:read

curl "{{API_URL}}/api/v1/on_call_shifts/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "OH3V5FYQEYJ6M",
      "name": "Demo single event",
      "type": "single_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T08:00:00",
      "duration": 10800,
      "users": ["U4DNY931HHJS5"]
    },
    {
      "id": "O9WTH7CKM3KZW",
      "name": "Demo recurrent event",
      "type": "recurrent_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T16:00:00",
      "duration": 10800,
      "frequency": "weekly",
      "interval": 2,
      "week_start": "SU",
      "by_day": ["MO", "WE", "FR"],
      "by_month": null,
      "by_monthday": null,
      "users": ["U4DNY931HHJS5"]
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

Note: The response is paginated. You may need to make multiple requests to get all records.

The following available filter parameters should be provided as GET arguments:

name (Exact match)
schedule_id (Exact match)

HTTP request

GET {{API_URL}}/api/v1/on_call_shifts/

Update OnCall shift

Required permission: grafana-oncall-app.schedules:write

curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Demo single event",
    "type": "single_event",
    "level": 0,
    "start": "2020-09-10T08:00:00",
    "duration": 10800,
    "users": [
        "U4DNY931HHJS5"
    ]
  }'

The above command returns JSON structured in the following way:

{
  "id": "OH3V5FYQEYJ6M",
  "name": "Demo single event",
  "type": "single_event",
  "team_id": null,
  "time_zone": null,
  "level": 0,
  "start": "2020-09-10T08:00:00",
  "duration": 10800,
  "users": ["U4DNY931HHJS5"]
}

HTTP request

PUT {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

Delete OnCall shift

Required permission: grafana-oncall-app.schedules:write

curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/