Create a swap request

POST

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

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.roundrobinbot.eu/v1/rotations/example/swap-requests"),
    Headers =
    {
        { "If-Match", "example" },
        { "Authorization", "Bearer <token>" },
    },
    Content = new StringContent("{ \"operationId\": \"example\", \"recipientUserId\": \"example\", \"legs\": [ { \"key\": \"example\", \"cellId\": \"example\", \"holderUserId\": \"example\", \"from\": \"2026-04-15T12:00:00Z\", \"to\": \"2026-04-15T12:00:00Z\" } ], \"reason\": \"example\", \"acknowledgedConflictIds\": [ \"example\" ] }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json-patch+json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

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

func main() {

  url := "https://api.roundrobinbot.eu/v1/rotations/example/swap-requests"

  payload := strings.NewReader("{ \"operationId\": \"example\", \"recipientUserId\": \"example\", \"legs\": [ { \"key\": \"example\", \"cellId\": \"example\", \"holderUserId\": \"example\", \"from\": \"2026-04-15T12:00:00Z\", \"to\": \"2026-04-15T12:00:00Z\" } ], \"reason\": \"example\", \"acknowledgedConflictIds\": [ \"example\" ] }")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("If-Match", "example")
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json-patch+json")

  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();

MediaType mediaType = MediaType.parse("application/json-patch+json");
RequestBody body = RequestBody.create(mediaType, "{ \"operationId\": \"example\", \"recipientUserId\": \"example\", \"legs\": [ { \"key\": \"example\", \"cellId\": \"example\", \"holderUserId\": \"example\", \"from\": \"2026-04-15T12:00:00Z\", \"to\": \"2026-04-15T12:00:00Z\" } ], \"reason\": \"example\", \"acknowledgedConflictIds\": [ \"example\" ] }");
Request request = new Request.Builder()
  .url("https://api.roundrobinbot.eu/v1/rotations/example/swap-requests")
  .post(body)
  .addHeader("If-Match", "example")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json-patch+json")
  .build();

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

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.roundrobinbot.eu/v1/rotations/example/swap-requests',
  headers: {
    'If-Match': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json-patch+json'
  },
  data: '{ "operationId": "example", "recipientUserId": "example", "legs": [ { "key": "example", "cellId": "example", "holderUserId": "example", "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z" } ], "reason": "example", "acknowledgedConflictIds": [ "example" ] }'
};

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';
const options = {
  method: 'POST',
  headers: {
    'If-Match': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json-patch+json'
  },
  body: '{ "operationId": "example", "recipientUserId": "example", "legs": [ { "key": "example", "cellId": "example", "holderUserId": "example", "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z" } ], "reason": "example", "acknowledgedConflictIds": [ "example" ] }'
};

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

curl --request POST \
  --url https://api.roundrobinbot.eu/v1/rotations/example/swap-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --header 'If-Match: example' \
  --data '{ "operationId": "example", "recipientUserId": "example", "legs": [ { "key": "example", "cellId": "example", "holderUserId": "example", "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z" } ], "reason": "example", "acknowledgedConflictIds": [ "example" ] }'

Requires a Slack member access token and If-Match from the latest preview. Creates a pending request. Duty remains unchanged until acceptance. Reuse operationId and the same body when retrying an uncertain result. A missing If-Match returns 428. On 412, refresh the preview before retrying.

Authorizations

Participant

Parameters

Path Parameters

rotationId

required

string

Header Parameters

If-Match

required

string

The ETag from your last read of this resource, sent back exactly as you received it, quotes included. The write happens only if nothing changed in between: a stale validator is answered 412 and nothing is written. Send * to write against whatever is current on purpose. Omitting the header is 428, never an unconditional write. https://docs.roundrobinbot.eu/api/conventions/#conditional-writes

Request Body^required

Two full future shifts to exchange with another Slack member in the same rotation.

object

operationId

A caller-generated identifier of at most 128 characters. Reuse it only for an identical retry. A repeated operation id is recognised for 30 days; after that it is treated as a new request.

string

recipientUserId

The other participant’s Slack user identifier. Must differ from the requester.

string

legs

Exactly two full shifts: one held by the requester and one held by the recipient. Both must start after the current time.

Array<object>

One duty interval offered by a swap participant.

object

key

A nonempty identifier unique to this interval within the request.

string

cellId

The identifier of the lane in a window, from the rotation plan.

string

holderUserId

The Slack user identifier of the person who holds this interval.

string

from

The full shift’s inclusive start, with UTC offset zero. Must be after the current time when proposing a swap.

string format: date-time

The full shift’s exclusive end, with UTC offset zero. Must be no more than six months after the current time.

string format: date-time

reason

An optional explanation of at most 2000 characters. Use an empty string to omit it.

string

acknowledgedConflictIds

Current conflict identifiers acknowledged for the interval this caller would receive.

Array<string>

Example^generated

{
  "operationId": "example",
  "recipientUserId": "example",
  "legs": [
    {
      "key": "example",
      "cellId": "example",
      "holderUserId": "example",
      "from": "2026-04-15T12:00:00Z",
      "to": "2026-04-15T12:00:00Z"
    }
  ],
  "reason": "example",
  "acknowledgedConflictIds": [
    "example"
  ]
}

Two full future shifts to exchange with another Slack member in the same rotation.

object

operationId

A caller-generated identifier of at most 128 characters. Reuse it only for an identical retry. A repeated operation id is recognised for 30 days; after that it is treated as a new request.

string

recipientUserId

The other participant’s Slack user identifier. Must differ from the requester.

string

legs

Exactly two full shifts: one held by the requester and one held by the recipient. Both must start after the current time.

Array<object>

One duty interval offered by a swap participant.

object

key

A nonempty identifier unique to this interval within the request.

string

cellId

The identifier of the lane in a window, from the rotation plan.

string

holderUserId

The Slack user identifier of the person who holds this interval.

string

from

The full shift’s inclusive start, with UTC offset zero. Must be after the current time when proposing a swap.

string format: date-time

The full shift’s exclusive end, with UTC offset zero. Must be no more than six months after the current time.

string format: date-time

reason

An optional explanation of at most 2000 characters. Use an empty string to omit it.

string

acknowledgedConflictIds

Current conflict identifiers acknowledged for the interval this caller would receive.

Array<string>

Example^generated

{
  "operationId": "example",
  "recipientUserId": "example",
  "legs": [
    {
      "key": "example",
      "cellId": "example",
      "holderUserId": "example",
      "from": "2026-04-15T12:00:00Z",
      "to": "2026-04-15T12:00:00Z"
    }
  ],
  "reason": "example",
  "acknowledgedConflictIds": [
    "example"
  ]
}

Two full future shifts to exchange with another Slack member in the same rotation.

object

operationId

A caller-generated identifier of at most 128 characters. Reuse it only for an identical retry. A repeated operation id is recognised for 30 days; after that it is treated as a new request.

string

recipientUserId

The other participant’s Slack user identifier. Must differ from the requester.

string

legs

Exactly two full shifts: one held by the requester and one held by the recipient. Both must start after the current time.

Array<object>

One duty interval offered by a swap participant.

object

key

A nonempty identifier unique to this interval within the request.

string

cellId

The identifier of the lane in a window, from the rotation plan.

string

holderUserId

The Slack user identifier of the person who holds this interval.

string

from

The full shift’s inclusive start, with UTC offset zero. Must be after the current time when proposing a swap.

string format: date-time

The full shift’s exclusive end, with UTC offset zero. Must be no more than six months after the current time.

string format: date-time

reason

An optional explanation of at most 2000 characters. Use an empty string to omit it.

string

acknowledgedConflictIds

Current conflict identifiers acknowledged for the interval this caller would receive.

Array<string>

Example^generated

{
  "operationId": "example",
  "recipientUserId": "example",
  "legs": [
    {
      "key": "example",
      "cellId": "example",
      "holderUserId": "example",
      "from": "2026-04-15T12:00:00Z",
      "to": "2026-04-15T12:00:00Z"
    }
  ],
  "reason": "example",
  "acknowledgedConflictIds": [
    "example"
  ]
}

Two full future shifts to exchange with another Slack member in the same rotation.

object

operationId

A caller-generated identifier of at most 128 characters. Reuse it only for an identical retry. A repeated operation id is recognised for 30 days; after that it is treated as a new request.

string

recipientUserId

The other participant’s Slack user identifier. Must differ from the requester.

string

legs

Exactly two full shifts: one held by the requester and one held by the recipient. Both must start after the current time.

Array<object>

One duty interval offered by a swap participant.

object

key

A nonempty identifier unique to this interval within the request.

string

cellId

The identifier of the lane in a window, from the rotation plan.

string

holderUserId

The Slack user identifier of the person who holds this interval.

string

from

The full shift’s inclusive start, with UTC offset zero. Must be after the current time when proposing a swap.

string format: date-time

The full shift’s exclusive end, with UTC offset zero. Must be no more than six months after the current time.

string format: date-time

reason

An optional explanation of at most 2000 characters. Use an empty string to omit it.

string

acknowledgedConflictIds

Current conflict identifiers acknowledged for the interval this caller would receive.

Array<string>

Example^generated

{
  "operationId": "example",
  "recipientUserId": "example",
  "legs": [
    {
      "key": "example",
      "cellId": "example",
      "holderUserId": "example",
      "from": "2026-04-15T12:00:00Z",
      "to": "2026-04-15T12:00:00Z"
    }
  ],
  "reason": "example",
  "acknowledgedConflictIds": [
    "example"
  ]
}

Responses

200

application/json

The saved result. deliveryState reports publication progress, not confirmed Slack receipt.

object

operationId

required

string

rotationVersion

required

integer format: int64

effectiveFrom

required

string format: date-time

request

required

A swap request, its rotation name and the actions available to this caller.

object

request

required

The request.

object

required

The request identifier.

string

rotationId

required

The rotation identifier.

string

requesterUserId

required

The user who made the request.

string

recipientUserId

required

The user asked to swap.

string

legs

required

The offered intervals.

Array<object>

An offered duty interval and its accepted assignment identifier, when present. phase is upcoming, running or ended for this leg at the time the response is built.

object

key

required

The key of this leg within the request.

string

rotationId

required

The rotation identifier.

string

cellId

required

The identifier of the lane in a window.

string

holderUserId

required

The user who holds the interval.

string

from

required

The inclusive interval start.

string format: date-time

required

The exclusive interval end.

string format: date-time

arrangementId

required

The accepted assignment identifier. Absent until the request is accepted.

null | string

phase

required

upcoming, running or ended for this leg at the instant the response is built.

string

reason

required

The reason given with the request.

string

revision

required

The revision of the request.

integer format: int64

state

required

The lifecycle state of the request.

string

phase

required

upcoming before the earliest leg starts, ended once the latest leg has ended, running between, at the instant the response is built.

string

capability

required

The actions available to the caller.

object

canAccept

required

Whether the caller may accept the request.

boolean

canDecline

required

Whether the caller may decline the request.

boolean

canCancel

required

Whether the caller may cancel the request.

boolean

reason

required

The reason the actions are unavailable. Absent when they are available.

null | string

reasonCode

required

The same word as reason, or null when the actions are available.

null | string

rotationName

required

The name of the rotation.

string

asOfUtc

required

The instant the state, phase and capabilities were evaluated.

string format: date-time

active

required

True while the request is pending or accepted.

boolean

actionable

required

True when the caller may accept, decline or cancel the request.

boolean

changesAtUtc

required

The earliest later instant at which the state, a phase, active or actionable changes by the clock alone. Null when none will.

null | string format: date-time

arrangements

required

Array<object>

An interval assignment. Its recorded terms remain distinct from actual served history.

object

required

The arrangement identifier.

string

rotationId

required

The rotation identifier.

string

cellId

required

The identifier of the lane in a window.

string

userId

required

The assigned person’s Slack user identifier.

string

from

required

The inclusive UTC start.

string format: date-time

required

The exclusive UTC end.

string format: date-time

revision

required

The arrangement revision used when changing or ending it.

integer format: int64

state

required

active or cancelled. An active record can describe an interval that has already ended.

string

kind

required

directAssignment, acceptedCover or swapLeg. Direct-assignment writes change or end only directAssignment.

string

phase

required

upcoming, running or ended, from from and to at the time the response is built.

string

changesAtUtc

required

The next instant at which phase changes, or null once it has ended.

null | string format: date-time

origin

One of:

null
object

null

originalSnapshot

One of:

null
object

null

Original duty segments on detail reads. Null on list reads or when no original record is available.

object

asOfUtc

required

The UTC time when the original duty was evaluated.

string format: date-time

from

required

The inclusive UTC start of the returned interval.

string format: date-time

required

The exclusive UTC end of the returned interval.

string format: date-time

complete

required

Whether every returned segment is resolved. An extension beyond the original recorded interval is unresolved.

boolean

segments

required

Original holders by interval, including periods with no assignee and unresolved periods.

Array<object>

Effective duty during part of an assignment interval.

object

from

required

The inclusive UTC start.

string format: date-time

required

The exclusive UTC end.

string format: date-time

userIds

required

Slack user identifiers of the effective holders. An empty list means no assignee only when resolved is true.

Array<string>

resolved

required

Whether the holders or absence of duty are known for this interval.

boolean

turnSelection

One of:

null
object

null

The recorded full or remaining turn, or null when no verified selection was saved. Use the arrangement’s From and To for the affected interval.

object

kind

required

fullTurn or remainingTurn.

string

from

required

The inclusive UTC start of the original turn, including any part already served.

string format: date-time

required

The exclusive UTC end of the original turn.

string format: date-time

deliveryState

required

string

Example^generated

{
  "operationId": "example",
  "rotationVersion": 1,
  "effectiveFrom": "2026-04-15T12:00:00Z",
  "request": {
    "request": {
      "id": "example",
      "rotationId": "example",
      "requesterUserId": "example",
      "recipientUserId": "example",
      "legs": [
        {
          "key": "example",
          "rotationId": "example",
          "cellId": "example",
          "holderUserId": "example",
          "from": "2026-04-15T12:00:00Z",
          "to": "2026-04-15T12:00:00Z",
          "arrangementId": "example",
          "phase": "example"
        }
      ],
      "reason": "example",
      "revision": 1,
      "state": "example",
      "phase": "example"
    },
    "capability": {
      "canAccept": true,
      "canDecline": true,
      "canCancel": true,
      "reason": "example",
      "reasonCode": "example"
    },
    "rotationName": "example",
    "asOfUtc": "2026-04-15T12:00:00Z",
    "active": true,
    "actionable": true,
    "changesAtUtc": "2026-04-15T12:00:00Z"
  },
  "arrangements": [
    {
      "id": "example",
      "rotationId": "example",
      "cellId": "example",
      "userId": "example",
      "from": "2026-04-15T12:00:00Z",
      "to": "2026-04-15T12:00:00Z",
      "revision": 1,
      "state": "example",
      "kind": "example",
      "phase": "example",
      "changesAtUtc": "2026-04-15T12:00:00Z",
      "origin": {
        "userIds": [
          "example"
        ],
        "complete": true
      },
      "originalSnapshot": {
        "asOfUtc": "2026-04-15T12:00:00Z",
        "from": "2026-04-15T12:00:00Z",
        "to": "2026-04-15T12:00:00Z",
        "complete": true,
        "segments": [
          {
            "from": "2026-04-15T12:00:00Z",
            "to": "2026-04-15T12:00:00Z",
            "userIds": [
              "example"
            ],
            "resolved": true
          }
        ]
      },
      "turnSelection": {
        "kind": "example",
        "from": "2026-04-15T12:00:00Z",
        "to": "2026-04-15T12:00:00Z"
      }
    }
  ],
  "deliveryState": "example"
}

Create a swap request

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Examplegenerated

Examplegenerated

Examplegenerated

Responses

200

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated