{"openapi":"3.1.0","info":{"title":"RotaCloud (BYOK) API","version":"0.1.0","description":"RotaCloud (BYOK) lets an AI assistant read your own RotaCloud data through the RotaCloud API with a key you supply (RotaCloud API key). Read-only: 9 tools (list_locations, get_location, list_roles, get_role, list_groups, list_leave_types, list_pay_periods, list_day_notes, list_shifts). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-rotacloud.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-rotacloud/docs"},"termsOfService":"https://connectorbay.com/byok-rotacloud/terms"},"servers":[{"url":"https://byok-rotacloud.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-rotacloud/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_locations":{"post":{"operationId":"list_locations","summary":"List the locations (sites) of the account with name, address, map position and time zone ID. Staff lists are not returne","description":"List the locations (sites) of the account with name, address, map position and time zone ID. Staff lists are not returned. Use for \"Which locations are set up in RotaCloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_deleted":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Also return deleted records.","title":"Include Deleted"},"only_visible":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Only locations visible to the key's user.","title":"Only Visible"}},"title":"list_locationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_location":{"post":{"operationId":"get_location","summary":"Get one location with name, address, map position and time zone ID. Use for \"Show me this RotaCloud location\".","description":"Get one location with name, address, map position and time zone ID. Use for \"Show me this RotaCloud location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ID of the location.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_locationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_roles":{"post":{"operationId":"list_roles","summary":"List the job roles used on the rota with name, colour and default break minutes. Staff assigned to a role are not return","description":"List the job roles used on the rota with name, colour and default break minutes. Staff assigned to a role are not returned. Use for \"Which roles exist in RotaCloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_deleted":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Also return deleted records.","title":"Include Deleted"}},"title":"list_rolesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_role":{"post":{"operationId":"get_role","summary":"Get one role with name, colour and default break minutes. Use for \"Show me this RotaCloud role\".","description":"Get one role with name, colour and default break minutes. Use for \"Show me this RotaCloud role\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"ID of the role.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_roleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_groups":{"post":{"operationId":"list_groups","summary":"List staff groups (such as Management or Finance) by name. Members are not returned. Use for \"Which staff groups exist i","description":"List staff groups (such as Management or Finance) by name. Members are not returned. Use for \"Which staff groups exist in RotaCloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_leave_types":{"post":{"operationId":"list_leave_types","summary":"List the leave types (holiday, sickness, other) with short name, colour and whether staff can request them. Use for \"Whi","description":"List the leave types (holiday, sickness, other) with short name, colour and whether staff can request them. Use for \"Which leave types are configured in RotaCloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_leave_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_pay_periods":{"post":{"operationId":"list_pay_periods","summary":"List pay periods with name, dates, and whether each is locked or finalised for payroll. Amounts are not returned. Use fo","description":"List pay periods with name, dates, and whether each is locked or finalised for payroll. Amounts are not returned. Use for \"What pay periods does RotaCloud have and are they finalised\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pay periods from this date (YYYY-MM-DD).","title":"Start"},"end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pay periods up to this date (YYYY-MM-DD).","title":"End"}},"title":"list_pay_periodsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_day_notes":{"post":{"operationId":"list_day_notes","summary":"List notes pinned to days on the rota (for example a bank holiday or an event) with title, message and the locations the","description":"List notes pinned to days on the rota (for example a bank holiday or an event) with title, message and the locations they apply to. Use for \"What day notes are on the RotaCloud rota\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only notes from this date (YYYY-MM-DD).","title":"Start"},"end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only notes up to this date (YYYY-MM-DD).","title":"End"},"location":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only notes for this location ID.","title":"Location"}},"title":"list_day_notesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_shifts":{"post":{"operationId":"list_shifts","summary":"List rota shifts in a time window with start and end time, break, location, role and whether the shift is open or publis","description":"List rota shifts in a time window with start and end time, break, location, role and whether the shift is open or published. Staff names and shift notes are not returned. Use for \"What shifts are on the RotaCloud rota this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Start of the window as a Unix timestamp in seconds.","title":"Start"},"end":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"End of the window as a Unix timestamp in seconds.","title":"End"},"open":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"true for only open (unassigned) shifts, false for only assigned ones.","title":"Open"},"published":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"true for only published shifts, false for only unpublished ones.","title":"Published"},"include_deleted":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Also return deleted records.","title":"Include Deleted"}},"title":"list_shiftsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}