List swap candidates

GET

/v1/rotations/{rotationId}/swap-requests/candidates

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.roundrobinbot.eu/v1/rotations/example/swap-requests/candidates?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z"),
    Headers =
    {
        { "Authorization", "Bearer <token>" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://api.roundrobinbot.eu/v1/rotations/example/swap-requests/candidates?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <token>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.roundrobinbot.eu/v1/rotations/example/swap-requests/candidates?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.roundrobinbot.eu/v1/rotations/example/swap-requests/candidates',
  params: {from: '2026-04-15T12:00:00Z', to: '2026-04-15T12:00:00Z'},
  headers: {Authorization: 'Bearer <token>'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.roundrobinbot.eu/v1/rotations/example/swap-requests/candidates?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.roundrobinbot.eu/v1/rotations/example/swap-requests/candidates?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'

Requires read:oncall and a key whose workspace and rotation selector permit this rotation. Supply UTC dates with from before to, a range of at most 31 days, and an end after the current time but no more than six months ahead. Invalid ranges return 422 with invalidSwapRange. External schedules return 409 with externalRotation. Returns eligible full future shifts overlapping the range, with their full start and end. Started shifts are excluded. selectableFrom equals from. New proposals must use both full shift boundaries. A started shift returns 409 with swapShiftStarted; a partial shift returns 409 with swapFullShiftRequired. Check complete and limitationCodes before treating the result as exhaustive. candidateHorizon means a turn ending beyond six months was omitted. Selecting a candidate does not create a swap request.

Authorizations

ApiKey

Parameters

Path Parameters

rotationId

required

string

Query Parameters

from

required

string format: date-time

required

string format: date-time

Responses

200

application/json

Available duty choices at asOfUtc. Check complete and limitationCodes before treating the list as exhaustive.

object

asOfUtc

required

The instant the list was read at.

string format: date-time

changesAtUtc

required

The start of the earliest item, the instant the list stops being current. Absent when the list is empty.

null | string format: date-time

complete

required

False when the list may omit shifts.

boolean

horizonUtc

required

The furthest instant a swap can reach, six calendar months after asOfUtc. A shift that ends after it is left out.

string format: date-time

items

required

The offered shifts.

Array<object>

A full future shift offered for selection, with its local time zone. selectableFrom equals from; started shifts are excluded.

object

cellId

required

string

from

required

string format: date-time

key

required

string

laneId

required

string

laneName

required

null | string

rotationId

required

string

selectableFrom

required

string format: date-time

timeZone

required

string

required

string format: date-time

userId

required

string

windowName

required

null | string

limitationCodes

required

The reasons the list may not be exhaustive, each as a code with the availability source it concerns when it concerns one. Empty when complete is true.

Array<object>

One reason a read is not exhaustive, with the availability source it concerns when it concerns one.

object

code

required

The reason, one of recurrenceExpansionIncomplete, manualAvailabilityUnavailable, googleCalendarUnavailable, proposalRecurrenceIncomplete, externalRotation, rotationDisabled, calendarFreshnessUnknown, projectionUnavailable, candidateHorizon, randomFutureUnknown or manualFutureContingent.

string

source

The availability source the reason is about, manualAvailability or googleCalendar. Absent when it is about no source.

null | string

Example^generated

{
  "asOfUtc": "2026-04-15T12:00:00Z",
  "changesAtUtc": "2026-04-15T12:00:00Z",
  "complete": true,
  "horizonUtc": "2026-04-15T12:00:00Z",
  "items": [
    {
      "cellId": "example",
      "from": "2026-04-15T12:00:00Z",
      "key": "example",
      "laneId": "example",
      "laneName": "example",
      "rotationId": "example",
      "selectableFrom": "2026-04-15T12:00:00Z",
      "timeZone": "example",
      "to": "2026-04-15T12:00:00Z",
      "userId": "example",
      "windowName": "example"
    }
  ],
  "limitationCodes": [
    {
      "code": "example",
      "source": "example"
    }
  ]
}

List swap candidates

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Examplegenerated

Example^generated