Servers Playground How we check Submit a server

RotaCloud MCP by usefulapi

Working · 479 ms

io.usefulapi/rotacloudv1.8.0 Domain verified

Read RotaCloud shifts, attendance, leave, availability and payroll; create shifts and handle leave.

Productivity

Source Website Registry entry

Try it

Call this server's tools from your browser. Nothing to install.

https://rotacloud.usefulapi.io/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

rotacloud_approve_leave_request

WRITE: approve a pending leave request (it becomes booked leave and the employee is notified). POST /leave_requests/{id}/approve.

request_idinteger, required

Leave request id.

admin_messagestring

Message to the employee.

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

RotaCloud MCP by usefulapi MCP server | mcptry

Tools (26)

rotacloud_approve_leave_request

WRITE: approve a pending leave request (it becomes booked leave and the employee is notified). POST /leave_requests/{id}/approve.

destructive

Argument	Type	Description
request_id*	integer	Leave request id.
admin_message	string	Message to the employee.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "request_id"
  ],
  "properties": {
    "request_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Leave request id.",
      "exclusiveMinimum": 0
    },
    "admin_message": {
      "type": "string",
      "maxLength": 2000,
      "description": "Message to the employee."
    }
  }
}

rotacloud_create_leave_request

WRITE: submit a leave request on behalf of an employee (sent as that user, for a manager to approve). POST /leave_requests with the User header.

destructive

Argument	Type	Description
message	string	Message from the employee to the manager.
user_id*	integer	The employee requesting leave (the request is made as this user).
end_date*	string	Last day (yyyy-mm-dd).
end_am_pm	string	'am' ends at midday (half day); default 'pm'.
start_date*	string	First day (yyyy-mm-dd).
start_am_pm	string	'pm' starts at midday (half day); default 'am'.
leave_type_id*	integer	Leave type id (see rotacloud_list_leave_types; must be requestable).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id",
    "leave_type_id",
    "start_date",
    "end_date"
  ],
  "properties": {
    "message": {
      "type": "string",
      "maxLength": 2000,
      "description": "Message from the employee to the manager."
    },
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "The employee requesting leave (the request is made as this user).",
      "exclusiveMinimum": 0
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day (yyyy-mm-dd)."
    },
    "end_am_pm": {
      "enum": [
        "am",
        "pm"
      ],
      "type": "string",
      "description": "'am' ends at midday (half day); default 'pm'."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day (yyyy-mm-dd)."
    },
    "start_am_pm": {
      "enum": [
        "am",
        "pm"
      ],
      "type": "string",
      "description": "'pm' starts at midday (half day); default 'am'."
    },
    "leave_type_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Leave type id (see rotacloud_list_leave_types; must be requestable).",
      "exclusiveMinimum": 0
    }
  }
}

rotacloud_create_shift

WRITE: create a shift on the rota. Leave user_id out for an open shift. Unpublished by default (employees see it once published). POST /shifts.

destructive

Argument	Type	Description
notes	string	Shift notes shown to the employee.
role_id	integer	Role id.
user_id	integer	Assigned user id; omit for an open shift.
end_time*	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
published	boolean	Publish immediately (default false).
start_time*	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
location_id*	integer	Location id.
minutes_break	integer	Unpaid break in minutes.

rotacloud_deny_leave_request

WRITE: deny a pending leave request (the employee is notified). POST /leave_requests/{id}/deny.

destructive

Argument	Type	Description
request_id*	integer	Leave request id.
admin_message	string	Reason shown to the employee.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "request_id"
  ],
  "properties": {
    "request_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Leave request id.",
      "exclusiveMinimum": 0
    },
    "admin_message": {
      "type": "string",
      "maxLength": 2000,
      "description": "Reason shown to the employee."
    }
  }
}

rotacloud_get_availability

Employees' availability per date in a range (available / unavailable times). GET /availability.

read-only

Argument	Type	Description
end*	string	Last date (yyyy-mm-dd).
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
start*	string	First date (yyyy-mm-dd).
users	array	Only these user ids.
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd)."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "users": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these user ids."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_get_leave_request

One leave request by id, with the per-day breakdown. GET /leave_requests/{id}.

read-only

Argument	Type	Description
request_id*	integer	Leave request id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "request_id"
  ],
  "properties": {
    "request_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Leave request id.",
      "exclusiveMinimum": 0
    }
  }
}

rotacloud_get_payroll

Payroll for one pay period, per employee: pay settings, attendance worked, paid/unpaid leave, overtime and pay totals. Contains pay data. GET /pay_periods/{id}/payroll.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.
pay_period_id*	integer	Pay period id (from rotacloud_list_pay_periods).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "pay_period_id"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "pay_period_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Pay period id (from rotacloud_list_pay_periods).",
      "exclusiveMinimum": 0
    }
  }
}

rotacloud_get_shift

One shift by id. GET /shifts/{id}.

read-only

Argument	Type	Description
shift_id*	integer	RotaCloud shift id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "shift_id"
  ],
  "properties": {
    "shift_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "RotaCloud shift id.",
      "exclusiveMinimum": 0
    }
  }
}

rotacloud_get_user

One employee by id. GET /users/{id}.

read-only

Argument	Type	Description
user_id*	integer	RotaCloud user id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id"
  ],
  "properties": {
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "RotaCloud user id.",
      "exclusiveMinimum": 0
    }
  }
}

rotacloud_list_accounts

The RotaCloud account(s) this API key belongs to: name, plan, time zone, employee count. GET /accounts.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_list_attendance

List time & attendance records (clock-in/out times, breaks, minutes late, hours, approval state) in a time range. GET /attendance.

read-only

Argument	Type	Description
end*	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
roles	array	Only these role ids.
start*	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
users	array	Only these user ids.
offset	integer	Index of the first result; pass the previous reply's next_offset.
approved	boolean	true = only approved records, false = only unapproved.
locations	array	Only these location ids.

rotacloud_list_clocked_in

Who is clocked in right now: user, location, role, clock-in time, minutes late and break state. GET /users_clocked_in.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_list_day_notes

List day notes (notices pinned to rota dates, e.g. events or deliveries), optionally for one location. GET /day_notes.

read-only

Argument	Type	Description
end	string	Last date (yyyy-mm-dd).
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
start	string	First date (yyyy-mm-dd).
offset	integer	Index of the first result; pass the previous reply's next_offset.
location	integer	Only notes for this location id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd)."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "location": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Only notes for this location id.",
      "exclusiveMinimum": 0
    }
  }
}

rotacloud_list_days_off

Employees' scheduled days off per date in a range. GET /days_off.

read-only

Argument	Type	Description
end*	string	Last date (yyyy-mm-dd).
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
start*	string	First date (yyyy-mm-dd).
users	array	Only these user ids.
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd)."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "users": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these user ids."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_list_holiday_allowances

Every employee's holiday allowance for a leave year (default and custom allowance, unit, carried over). GET /holiday_allowances/{year}.

read-only

Argument	Type	Description
year*	integer	Leave year, e.g. 2026.
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "year"
  ],
  "properties": {
    "year": {
      "type": "integer",
      "maximum": 2100,
      "minimum": 2000,
      "description": "Leave year, e.g. 2026."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_list_leave

List booked leave (holiday, sickness, etc.) with type, user, dates, hours and status. Filter by date range or leave year, users and leave types; pending/denied/expired requests are excluded unless asked for. GET /leave.

read-only

Argument	Type	Description
end	string	Last date (yyyy-mm-dd).
year	integer	Leave year instead of a date range.
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
start	string	First date (yyyy-mm-dd).
types	array	Only these leave type ids (see rotacloud_list_leave_types).
users	array	Only these user ids.
offset	integer	Index of the first result; pass the previous reply's next_offset.
include_denied	boolean	Include denied leave requests.
include_deleted	boolean

rotacloud_list_leave_requests

List leave requests awaiting a decision (and past ones): user, leave type, dates, half days, the employee's message. GET /leave_requests.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.
include_deleted	boolean	Include deleted requests.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted requests."
    }
  }
}

rotacloud_list_leave_types

List leave types (Holiday, Sickness, Unpaid, ...) with id, short name and whether employees can request them. GET /leave_types.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_list_locations

List locations (sites/branches) with address, time zone and managers. GET /locations.

read-only

Argument	Type	Description
ids	array	Only these location ids.
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.
include_deleted	boolean	Include deleted locations.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these location ids."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted locations."
    }
  }
}

rotacloud_list_pay_periods

List pay periods overlapping a date range (id, name, start/end date, locked). GET /pay_periods.

read-only

Argument	Type	Description
end*	string	Last date (yyyy-mm-dd).
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
start*	string	First date (yyyy-mm-dd).
offset	integer	Index of the first result; pass the previous reply's next_offset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd)."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    }
  }
}

rotacloud_list_roles

List job roles (positions) with colour, default break and pay rate. GET /roles.

read-only

Argument	Type	Description
ids	array	Only these role ids.
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.
include_deleted	boolean	Include deleted roles.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these role ids."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted roles."
    }
  }
}

rotacloud_list_shifts

List rota shifts in a time range: start/end times (Unix seconds), break, assigned user (null = open shift), location, role, notes, published and acknowledged state. Filter by users, locations, roles, open or published. GET /shifts.

read-only

Argument	Type	Description
end*	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
open	boolean	true = only open (unassigned) shifts, false = only assigned shifts.
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
roles	array	Only shifts with these role ids.
start*	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
users	array	Only shifts of these user ids (add 0 to include open shifts).
offset	integer	Index of the first result; pass the previous reply's next_offset.

rotacloud_list_swap_requests

List shift swap requests with their status, the shifts and the users involved. GET /swap_requests.

read-only

Argument	Type	Description
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.
include_deleted	boolean	Include deleted swap requests.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted swap requests."
    }
  }
}

rotacloud_list_users

List employees (users) with their level, roles, locations, contact details and pay settings. Use it to map user ids in shifts, leave and attendance to names. GET /users.

read-only

Argument	Type	Description
ids	array	Only these user ids.
limit	integer	Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).
offset	integer	Index of the first result; pass the previous reply's next_offset.
locations	array	Only users in these location ids.
include_deleted	boolean	Include deleted (former) users.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these user ids."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only users in these location ids."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted (former) users."
    }
  }
}

rotacloud_publish_shifts

WRITE: publish shifts so the assigned employees see them (and get notified). POST /shifts_published.

destructive

Argument	Type	Description
shift_ids*	array	Ids of the shifts to publish.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "shift_ids"
  ],
  "properties": {
    "shift_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "Ids of the shifts to publish."
    }
  }
}

rotacloud_update_shift

WRITE: change a shift's times, assignee, location, role, break, notes or published state. Only the fields you pass change. POST /shifts/{id}.

destructive

Argument	Type	Description
notes	string	Shift notes.
role_id	integer	New role id.
user_id	any	New assignee; null makes it an open shift.
end_time	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
shift_id*	integer	Shift id.
published	boolean	Published state.
start_time	any	Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z).
location_id	integer	New location id.
minutes_break	integer

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start_time",
    "end_time",
    "location_id"
  ],
  "properties": {
    "notes": {
      "type": "string",
      "maxLength": 2000,
      "description": "Shift notes shown to the employee."
    },
    "role_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Role id.",
      "exclusiveMinimum": 0
    },
    "user_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Assigned user id; omit for an open shift.",
      "exclusiveMinimum": 0
    },
    "end_time": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "published": {
      "type": "boolean",
      "description": "Publish immediately (default false)."
    },
    "start_time": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "location_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Location id.",
      "exclusiveMinimum": 0
    },
    "minutes_break": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Unpaid break in minutes."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these role ids."
    },
    "start": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "users": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these user ids."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "approved": {
      "type": "boolean",
      "description": "true = only approved records, false = only unapproved."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only these location ids."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted records."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "open": {
      "type": "boolean",
      "description": "true = only open (unassigned) shifts, false = only assigned shifts."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "description": "Results per page, 1-500 (RotaCloud may cap it lower; the reply's total and next_offset show what is left).",
      "exclusiveMinimum": 0
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only shifts with these role ids."
    },
    "start": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "users": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 0
      },
      "description": "Only shifts of these user ids (add 0 to include open shifts)."
    },
    "offset": {
      "type": "integer",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Index of the first result; pass the previous reply's next_offset."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "exclusiveMinimum": 0
      },
      "description": "Only shifts at these location ids."
    },
    "published": {
      "type": "boolean",
      "description": "true = only published shifts, false = only unpublished (draft) shifts."
    },
    "include_deleted": {
      "type": "boolean",
      "description": "Include deleted shifts."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "shift_id"
  ],
  "properties": {
    "notes": {
      "type": "string",
      "maxLength": 2000,
      "description": "Shift notes."
    },
    "role_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "New role id.",
      "exclusiveMinimum": 0
    },
    "user_id": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "New assignee; null makes it an open shift."
    },
    "end_time": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "shift_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Shift id.",
      "exclusiveMinimum": 0
    },
    "published": {
      "type": "boolean",
      "description": "Published state."
    },
    "start_time": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        {
          "type": "string"
        }
      ],
      "description": "Unix timestamp (seconds), an ISO 8601 date (2026-10-12 = 00:00 UTC) or an ISO 8601 date-time with a time zone (2026-10-12T09:00:00+01:00 or ...Z)."
    },
    "location_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "New location id.",
      "exclusiveMinimum": 0
    },
    "minutes_break": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Unpaid break in minutes."
    }
  }
}