--- title: "Shift swap requests HTTP API | Grafana Cloud documentation" description: "Shift swap requests HTTP API Create a shift swap request Required permission: grafana-irm-app.schedules:write shell Copy curl \"{{API_URL}}/api/v1/shift_swaps/\" \\ --request POST \\ --header \"Authorization: Bearer meowmeowmeow\" \\ --header \"Content-Type: application/json\" \\ --header \"X-Grafana-URL: https://your-stack.grafana.net\" \\ --data '{ \"schedule\": \"SRJWJCMKD68AL\", \"swap_start\": \"2026-06-11T00:00:00Z\", \"swap_end\": \"2026-07-19T22:00:00Z\", \"description\": \"Anyone to cover my shifts?\", \"beneficiary\": \"UWJWIN8MQ1GYL\" }' 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). # Shift swap requests HTTP API ## Create a shift swap request **Required permission**: `grafana-irm-app.schedules:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/shift_swaps/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "schedule": "SRJWJCMKD68AL", "swap_start": "2026-06-11T00:00:00Z", "swap_end": "2026-07-19T22:00:00Z", "description": "Anyone to cover my shifts?", "beneficiary": "UWJWIN8MQ1GYL" }' ``` 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 { "benefactor": null, "beneficiary": "UWJWIN8MQ1GYL", "created_at": "2023-08-11T19:20:17.064677Z", "description": "Anyone to cover my shifts?", "id": "SSRG1TDNBMJQ1NC", "schedule": "SRJWJCMKD68AL", "shifts": [ { "all_day": false, "calendar_type": 0, "end": "2026-06-11T03:00:00Z", "is_empty": false, "is_gap": false, "is_override": false, "missing_users": [], "priority_level": 2, "shift": { "pk": "OTI13GNNE5V1L" }, "source": "web", "start": "2026-06-11T00:00:00Z", "users": [ { "avatar_full": "http://avatar.url", "display_name": "testing", "email": "testing", "pk": "UWJWIN8MQ1GYL", "swap_request": { "pk": "SSRG1TDNBMJQ1NC" } } ] } ], "status": "open", "swap_end": "2026-07-19T22:00:00.000000Z", "swap_start": "2026-06-11T00:00:00.000000Z", "updated_at": "2023-08-11T19:20:17.064922Z" } ``` Expand table | Parameter | Unique | Required | Description | |---------------|--------|----------|-------------------------------------------------------------------------------------| | `schedule` | No | Yes | ID of the schedule. | | `swap_start` | No | Yes | Start date/time for the swap request. Must be a ISO 8601 formatted datetime string. | | `swap_end` | No | No | End date/time for the swap request. Must be a ISO 8601 formatted datetime string. | | `description` | No | Optional | A description message to be displayed along the request. | | `beneficiary` | No | Yes | ID of the user requesting the swap. | **HTTP request** `POST {{API_URL}}/api/v1/shift_swaps/` ## Get a shift swap request **Required permission**: `grafana-irm-app.schedules:read` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` 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 { "benefactor": null, "beneficiary": "UWJWIN8MQ1GYL", "created_at": "2023-08-11T19:20:17.064677Z", "description": "Anyone to cover my shifts?", "id": "SSRG1TDNBMJQ1NC", "schedule": "SRJWJCMKD68AL", "shifts": [ { "all_day": false, "calendar_type": 0, "end": "2026-06-11T03:00:00Z", "is_empty": false, "is_gap": false, "is_override": false, "missing_users": [], "priority_level": 2, "shift": { "pk": "OTI13GNNE5V1L" }, "source": "web", "start": "2026-06-11T00:00:00Z", "users": [ { "avatar_full": "http://avatar.url", "display_name": "testing", "email": "testing", "pk": "UWJWIN8MQ1GYL", "swap_request": { "pk": "SSRG1TDNBMJQ1NC" } } ] } ], "status": "open", "swap_end": "2026-07-19T22:00:00.000000Z", "swap_start": "2026-06-11T00:00:00.000000Z", "updated_at": "2023-08-11T19:20:17.064922Z" } ``` **HTTP request** `GET {{API_URL}}/api/v1/shift_swaps//` ## List shift swap requests **Required permission**: `grafana-irm-app.schedules:read` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/shift_swaps/" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` 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, "current_page_number": 1, "next": null, "page_size": 50, "previous": null, "results": [ { "benefactor": "UWJWIN8MQ1GYL", "beneficiary": "UCGEIXI1MR1NZ", "created_at": "2023-08-07T18:44:15.249679Z", "description": "Taking a few days off.", "id": "SSRK2EH2TR6E4F9", "schedule": "SRZZFY1QI9FLL", "status": "taken", "swap_end": "2024-09-29T03:00:18.000000Z", "swap_start": "2024-09-26T03:00:18.000000Z", "updated_at": "2024-08-07T18:44:15.249960Z" }, { "benefactor": null, "beneficiary": "UWJWIN8MQ1GYL", "created_at": "2023-08-11T19:20:17.064677Z", "description": "Anyone to cover my shifts?", "id": "SSRG1TDNBMJQ1NC", "schedule": "SRJWJCMKD68AL", "status": "open", "swap_end": "2026-07-19T22:00:00.000000Z", "swap_start": "2026-06-11T00:00:00.000000Z", "updated_at": "2023-08-11T19:20:17.064922Z" } ], "total_pages": 1 } ``` > **Note**: The response is [paginated](/docs/grafana-cloud/alerting-and-irm/irm/reference/oncall-api/#pagination). You may need to make multiple requests to get all records. The following available filter parameters may be provided as a `GET` arguments: - `starting_after` (an ISO 8601 timestamp string, filter requests starting after the specified datetime) - `schedule_id` (Exact match, schedule ID) - `beneficiary` (Exact match, user ID) - `benefactor` (Exact match, user ID) - `open_only` (set to `true` to filter active untaken requests only) **HTTP request** `GET {{API_URL}}/api/v1/shift_swaps/` ## Update a shift swap request **Required permission**: `grafana-irm-app.schedules:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \ --request PUT \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "schedule": "SRJWJCMKD68AL", "swap_start": "2026-06-11T00:00:00Z", "swap_end": "2026-07-20T22:00:00Z" }' ``` 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 { "benefactor": null, "beneficiary": "UWJWIN8MQ1GYL", "created_at": "2023-08-11T19:20:17.064677Z", "description": "Anyone to cover my shifts?", "id": "SSRG1TDNBMJQ1NC", "schedule": "SRJWJCMKD68AL", "shifts": [ { "all_day": false, "calendar_type": 0, "end": "2026-06-11T03:00:00Z", "is_empty": false, "is_gap": false, "is_override": false, "missing_users": [], "priority_level": 2, "shift": { "pk": "OTI13GNNE5V1L" }, "source": "web", "start": "2026-06-11T00:00:00Z", "users": [ { "avatar_full": "http://avatar.url", "display_name": "testing", "email": "testing", "pk": "UWJWIN8MQ1GYL", "swap_request": { "pk": "SSRG1TDNBMJQ1NC" } } ] } ], "status": "open", "swap_end": "2026-07-20T22:00:00.000000Z", "swap_start": "2026-06-11T00:00:00.000000Z", "updated_at": "2023-08-11T19:45:53.096811Z" } ``` **HTTP request** `PUT {{API_URL}}/api/v1/shift_swaps//` ## Delete a shift swap request **Required permission**: `grafana-irm-app.schedules:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \ --request DELETE \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `DELETE {{API_URL}}/api/v1/shift_swaps//` ## Take a shift swap request **Required permission**: `grafana-irm-app.schedules:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/take" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "benefactor": "UCGEIXI1MR1NZ" }' ``` 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 { "benefactor": "UCGEIXI1MR1NZ", "beneficiary": "UWJWIN8MQ1GYL", "created_at": "2023-08-11T19:20:17.064677Z", "description": "Anyone to cover my shifts?", "id": "SSRG1TDNBMJQ1NC", "schedule": "SRJWJCMKD68AL", "shifts": [ { "all_day": false, "calendar_type": 0, "end": "2026-06-11T03:00:00Z", "is_empty": false, "is_gap": false, "is_override": false, "missing_users": [], "priority_level": 2, "shift": { "pk": "OTI13GNNE5V1L" }, "source": "web", "start": "2026-06-11T00:00:00Z", "users": [ { "avatar_full": "http://avatar.url", "display_name": "anotherone", "email": "anotherone", "pk": "UCGEIXI1MR1NZ", "swap_request": { "pk": "SSRG1TDNBMJQ1NC", "user": { "avatar_full": "http://avatar.url", "display_name": "testing", "email": "testing", "pk": "UWJWIN8MQ1GYL" } } } ] } ], "status": "taken", "swap_end": "2026-07-20T22:00:00.000000Z", "swap_start": "2026-06-11T00:00:00.000000Z", "updated_at": "2023-08-11T19:51:38.622037Z" } ``` Expand table | Parameter | Unique | Required | Description | |--------------|--------|----------|---------------------------------| | `benefactor` | No | Yes | ID of the user taking the swap. | **HTTP request** `POST {{API_URL}}/api/v1/shift_swaps//take`