Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation

OnCall

API reference

OnCall shifts HTTP API

Open source

Create an OnCall shift

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

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

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
}

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

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

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>/