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

Shift swaps HTTP API

Open source

Create a shift swap request

curl "{{API_URL}}/api/v1/shift_swaps/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --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:

{
   "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"
}

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

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

The above command returns JSON structured in the following way:

{
   "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/<SHIFT_SWAP_REQUEST_ID>/

List shift swap requests

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

The above command returns JSON structured in the following way:

{
   "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
}

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

curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --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:

{
   "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/<SHIFT_SWAP_REQUEST_ID>/

Delete a shift swap request

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

HTTP request

DELETE {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/

Take a shift swap request

curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/take" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
        "benefactor": "UCGEIXI1MR1NZ"
  }'

The above command returns JSON structured in the following way:

{
   "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"
}