--- title: "OnCall shifts HTTP API | Grafana OnCall documentation" description: "Create an OnCall shift shell Copy 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:" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Create an OnCall shift shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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" ] } ``` Expand table | 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 see [time zones](https://en.wikipedia.org/wiki/List_of_tz_database_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: `daily`, `weekly`, `monthly`. | | `interval` | No | Optional | This parameter takes a positive integer that represents the intervals that the recurrence rule repeats. | | `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` | Please see [RFC 5545](https://tools.ietf.org/html/rfc5545#section-3.3.10) for more information about recurrence rules. **HTTP request** `POST {{API_URL}}/api/v1/on_call_shifts/` # Get OnCall shifts shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/on_call_shifts/SBM7DV7BKFUYU/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "Content-Type: application/json" \ ``` The above command returns JSON structured in the following way: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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//` # List OnCall shifts shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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" ] } ] } ``` 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 shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/on_call_shifts/S3Z477AHDXTMF/" \ --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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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//` # Delete OnCall shift shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/on_call_shifts/S3Z477AHDXTMF/" \ --request DELETE \ --header "Authorization: meowmeowmeow" \ --header "Content-Type: application/json" ``` **HTTP request** `DELETE {{API_URL}}/api/v1/on_call_shifts//`