Scheduling API

23 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/scheduling/me

My published shifts (default: the next 14 days), open shifts I may pick up, and my swaps

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
from	query	string	no
to	query	string	no

Responses

200 Success. object

• employeeIdstring (uuid) or nullrequired
• fromstringrequired
• tostringrequired
• shiftsarray of objectrequired

  • idstring (uuid)required
  • rosterIdstring (uuid)required
  • scopeLabelstringrequired
  • datestringrequired
  • kindenumrequired

    one of "shift", "rest"

  • startstring | nullrequired
  • endstring | nullrequired
  • breakMinutesnumberrequired
  • paidMinutesnumberrequired
  • templateCodestring | nullrequired
  • colourenumrequired

    one of "plain", "kuning", "biru", "oren", "ink"

  • notestring | nullrequired
  • pendingSwapbooleanrequired
• weeksarray of objectrequired

  • weekStartstringrequired
  • publishedbooleanrequired
• openShiftsarray of objectrequired

  • idstring (uuid)required
  • rosterIdstring (uuid)required
  • scopeLabelstringrequired
  • datestringrequired
  • kindenumrequired

    one of "shift", "rest"

  • startstring | nullrequired
  • endstring | nullrequired
  • breakMinutesnumberrequired
  • paidMinutesnumberrequired
  • templateCodestring | nullrequired
  • colourenumrequired

    one of "plain", "kuning", "biru", "oren", "ink"

  • notestring | nullrequired
  • pendingSwapbooleanrequired
• swapsarray of objectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "swap", "giveaway", "pickup"

  • statusenumrequired

    one of "pending_peer", "pending_approval", "approved", "rejected", "declined", "cancelled", "expired"

  • directionenumrequired

    one of "outgoing", "incoming", "other"

  • requesterobjectrequired

    • idstring (uuid)required
    • namestringrequired
  • peerobject or nullrequired

    • idstring (uuid)required
    • namestringrequired
  • shiftobjectrequired

    • idstring (uuid)required
    • datestringrequired
    • timestringrequired
  • peerShiftobject or nullrequired

    • idstring (uuid)required
    • datestringrequired
    • timestringrequired
  • notestring | nullrequired
  • reasonstring | nullrequired
  • approvalRequestIdstring (uuid) or nullrequired
  • createdAtstringrequired
  • expiresAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

GET/api/v1/scheduling/rosters

A roster week by scope: the working copy with conflicts for editors, the published copy for staff

Access

Permission rosters:read

Parameters

Name	In	Type	Required
weekStart	query	string	yes
locationId	query	string (uuid)	no
departmentId	query	string (uuid)	no

Responses

200 Success. object

• rosterobjectrequired

  • idstring (uuid) or nullrequired
  • weekStartstringrequired
  • locationIdstring (uuid) or nullrequired
  • departmentIdstring (uuid) or nullrequired
  • scopeLabelstringrequired
  • statusenumrequired

    one of "none", "draft", "published"

  • versionnumberrequired
  • hasChangesbooleanrequired
  • publishedAtstring | nullrequired
• modeenumrequired

  one of "edit", "published"

• canEditbooleanrequired
• daysarray of objectrequired

  • datestringrequired
  • holidaystring | nullrequired
  • minutesnumberrequired
• employeesarray of objectrequired

  • idstring (uuid)required
  • namestringrequired
  • employeeNumberstringrequired
  • scheduleenum or nullrequired

    one of "fixed", "shift"

  • editablebooleanrequired
  • minutesnumberrequired
  • restDayAssumedstring | nullrequired
  • warningsarray of objectrequired

    • kindenumrequired

      one of "overlap", "on_leave", "outside_employment", "pending_leave", "public_holiday", "rest_day", "daily_hours", "overtime", "weekly_hours", "no_rest_day", "ot_cap"

    • severityenumrequired

      one of "block", "ack", "warning", "hint"

    • labelstringrequired
    • messagestringrequired
    • sourcestring | nullrequired
• shiftsarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid) or nullrequired
  • kindenumrequired

    one of "shift", "rest"

  • datestringrequired
  • startsAtstring | nullrequired
  • endsAtstring | nullrequired
  • startstring | nullrequired
  • endstring | nullrequired
  • breakMinutesnumberrequired
  • paidMinutesnumberrequired
  • templateIdstring (uuid) or nullrequired
  • templateCodestring | nullrequired
  • colourenumrequired

    one of "plain", "kuning", "biru", "oren", "ink"

  • notestring | nullrequired
  • updatedAtstringrequired
  • conflictsarray of objectrequired

    • kindenumrequired

      one of "overlap", "on_leave", "outside_employment", "pending_leave", "public_holiday", "rest_day", "daily_hours", "overtime", "weekly_hours", "no_rest_day", "ot_cap"

    • severityenumrequired

      one of "block", "ack", "warning", "hint"

    • labelstringrequired
    • messagestringrequired
    • sourcestring | nullrequired
  • pendingSwapbooleanrequired
• toAcknowledgearray of objectrequired

  • shiftIdstring (uuid)required
  • kindstringrequired
  • employeeNamestringrequired
  • datestringrequired
  • messagestringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/scheduling/rosters

Open (or create) the draft roster for a scope and week

Access

Permission rosters:create

Request body

application/json, object, required

• weekStartstringrequired
• locationIdstring (uuid) or null
• departmentIdstring (uuid) or null

Responses

200 Success. object

• idstring (uuid)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

GET/api/v1/scheduling/rosters/{id}

A roster week by id

Access

Permission rosters:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• rosterobjectrequired

  • idstring (uuid) or nullrequired
  • weekStartstringrequired
  • locationIdstring (uuid) or nullrequired
  • departmentIdstring (uuid) or nullrequired
  • scopeLabelstringrequired
  • statusenumrequired

    one of "none", "draft", "published"

  • versionnumberrequired
  • hasChangesbooleanrequired
  • publishedAtstring | nullrequired
• modeenumrequired

  one of "edit", "published"

• canEditbooleanrequired
• daysarray of objectrequired

  • datestringrequired
  • holidaystring | nullrequired
  • minutesnumberrequired
• employeesarray of objectrequired

  • idstring (uuid)required
  • namestringrequired
  • employeeNumberstringrequired
  • scheduleenum or nullrequired

    one of "fixed", "shift"

  • editablebooleanrequired
  • minutesnumberrequired
  • restDayAssumedstring | nullrequired
  • warningsarray of objectrequired

    • kindenumrequired

      one of "overlap", "on_leave", "outside_employment", "pending_leave", "public_holiday", "rest_day", "daily_hours", "overtime", "weekly_hours", "no_rest_day", "ot_cap"

    • severityenumrequired

      one of "block", "ack", "warning", "hint"

    • labelstringrequired
    • messagestringrequired
    • sourcestring | nullrequired
• shiftsarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid) or nullrequired
  • kindenumrequired

    one of "shift", "rest"

  • datestringrequired
  • startsAtstring | nullrequired
  • endsAtstring | nullrequired
  • startstring | nullrequired
  • endstring | nullrequired
  • breakMinutesnumberrequired
  • paidMinutesnumberrequired
  • templateIdstring (uuid) or nullrequired
  • templateCodestring | nullrequired
  • colourenumrequired

    one of "plain", "kuning", "biru", "oren", "ink"

  • notestring | nullrequired
  • updatedAtstringrequired
  • conflictsarray of objectrequired

    • kindenumrequired

      one of "overlap", "on_leave", "outside_employment", "pending_leave", "public_holiday", "rest_day", "daily_hours", "overtime", "weekly_hours", "no_rest_day", "ot_cap"

    • severityenumrequired

      one of "block", "ack", "warning", "hint"

    • labelstringrequired
    • messagestringrequired
    • sourcestring | nullrequired
  • pendingSwapbooleanrequired
• toAcknowledgearray of objectrequired

  • shiftIdstring (uuid)required
  • kindstringrequired
  • employeeNamestringrequired
  • datestringrequired
  • messagestringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/scheduling/rosters/{id}/clear

Remove every shift you may edit from this week's working copy

Access

Permission rosters:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• removednumberrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/scheduling/rosters/{id}/copy-previous

Copy last week's shifts into this roster, skipping people who left or moved

Access

Permission rosters:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• copiednumberrequired
• skippedarray of objectrequired

  • employeeNamestringrequired
  • datestringrequired
  • reasonstringrequired
• messagestringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

GET/api/v1/scheduling/rosters/{id}/export.csv

Roster week as CSV (one row per shift, with conflicts)

Access

Permission rosters:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 CSV file text/csv

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/scheduling/rosters/{id}/publish

Publish the working copy: staff, attendance, leave and payroll see it; changed staff are notified

Every `on_leave` and `outside_employment` conflict must be listed in `acknowledge`, or the call answers 409 `unacknowledged_conflicts` with the list.

Access

Permission rosters:publish

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• acknowledgearray of object

  default []

  • shiftIdstring (uuid)required
  • kindstringrequired

    min length 1 · max length 40

Responses

200 Success. object

• versionnumberrequired
• publishedAtstringrequired
• notifiednumberrequired
• changedEmployeesnumberrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 shift_overlap, unacknowledged_conflicts

POST/api/v1/scheduling/rosters/{id}/shifts

Add a shift, an open shift or a rest day to the working copy

Access

Permission rosters:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• employeeIdstring (uuid) or nullrequired
• datestringrequired
• kindenum

  one of "shift", "rest" · default "shift"

• templateIdstring (uuid) or null
• startTimestring
• endTimestring
• breakMinutesinteger

  min 0 · max 240

• notestring or null

  max length 200

Responses

201 Success. object

• idstring (uuid)required
• rosterIdstring (uuid)required
• updatedAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict, shift_overlap
• 422 not_eligible

GET/api/v1/scheduling/scopes

Locations and departments a roster can be built for, and the caller's own

Access

Permission rosters:read

Responses

200 Success. object

• locationsarray of objectrequired

  • idstring (uuid)required
  • namestringrequired
• departmentsarray of objectrequired

  • idstring (uuid)required
  • namestringrequired
• mineobjectrequired

  • locationIdstring (uuid) or nullrequired
  • departmentIdstring (uuid) or nullrequired
• canEditbooleanrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

PATCH/api/v1/scheduling/shifts/{id}

Change or move a shift in the working copy (409 stale when someone else changed it)

Access

Permission rosters:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• employeeIdstring (uuid) or nullrequired
• datestringrequired
• kindenum

  one of "shift", "rest" · default "shift"

• templateIdstring (uuid) or null
• startTimestring
• endTimestring
• breakMinutesinteger

  min 0 · max 240

• notestring or null

  max length 200

• expectedUpdatedAtstring

Responses

200 Success. object

• idstring (uuid)required
• rosterIdstring (uuid)required
• updatedAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict, shift_overlap, stale
• 422 not_eligible

DELETE/api/v1/scheduling/shifts/{id}

Remove a shift from the working copy (open swap requests on it are cancelled)

Access

Permission rosters:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

GET/api/v1/scheduling/swaps

My swap and pickup requests (sent and received)

Access

Any signed-in member (own data only)

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "swap", "giveaway", "pickup"

  • statusenumrequired

    one of "pending_peer", "pending_approval", "approved", "rejected", "declined", "cancelled", "expired"

  • directionenumrequired

    one of "outgoing", "incoming", "other"

  • requesterobjectrequired

    • idstring (uuid)required
    • namestringrequired
  • peerobject or nullrequired

    • idstring (uuid)required
    • namestringrequired
  • shiftobjectrequired

    • idstring (uuid)required
    • datestringrequired
    • timestringrequired
  • peerShiftobject or nullrequired

    • idstring (uuid)required
    • datestringrequired
    • timestringrequired
  • notestring | nullrequired
  • reasonstring | nullrequired
  • approvalRequestIdstring (uuid) or nullrequired
  • createdAtstringrequired
  • expiresAtstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

POST/api/v1/scheduling/swaps

Offer a shift to a colleague (swap or give-away), or ask for an open shift

Access

Permission shift_swaps:create

Request body

application/json, object, required

• kindenumrequired

  one of "swap", "giveaway", "pickup"

• shiftIdstring (uuid)required
• peerEmployeeIdstring (uuid) or null
• peerShiftIdstring (uuid) or null
• notestring or null

  max length 200

Responses

201 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "swap", "giveaway", "pickup"

• statusenumrequired

  one of "pending_peer", "pending_approval", "approved", "rejected", "declined", "cancelled", "expired"

• directionenumrequired

  one of "outgoing", "incoming", "other"

• requesterobjectrequired

  • idstring (uuid)required
  • namestringrequired
• peerobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• shiftobjectrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• peerShiftobject or nullrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• notestring | nullrequired
• reasonstring | nullrequired
• approvalRequestIdstring (uuid) or nullrequired
• createdAtstringrequired
• expiresAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict, shift_overlap, stale
• 422 not_eligible

POST/api/v1/scheduling/swaps/{id}/accept

Accept a colleague's swap offer (sends it for approval)

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "swap", "giveaway", "pickup"

• statusenumrequired

  one of "pending_peer", "pending_approval", "approved", "rejected", "declined", "cancelled", "expired"

• directionenumrequired

  one of "outgoing", "incoming", "other"

• requesterobjectrequired

  • idstring (uuid)required
  • namestringrequired
• peerobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• shiftobjectrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• peerShiftobject or nullrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• notestring | nullrequired
• reasonstring | nullrequired
• approvalRequestIdstring (uuid) or nullrequired
• createdAtstringrequired
• expiresAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found
• 409 conflict, shift_overlap, stale

POST/api/v1/scheduling/swaps/{id}/cancel

Cancel my swap or pickup request before it is approved

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "swap", "giveaway", "pickup"

• statusenumrequired

  one of "pending_peer", "pending_approval", "approved", "rejected", "declined", "cancelled", "expired"

• directionenumrequired

  one of "outgoing", "incoming", "other"

• requesterobjectrequired

  • idstring (uuid)required
  • namestringrequired
• peerobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• shiftobjectrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• peerShiftobject or nullrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• notestring | nullrequired
• reasonstring | nullrequired
• approvalRequestIdstring (uuid) or nullrequired
• createdAtstringrequired
• expiresAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found
• 409 conflict

POST/api/v1/scheduling/swaps/{id}/decline

Decline a colleague's swap offer

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "swap", "giveaway", "pickup"

• statusenumrequired

  one of "pending_peer", "pending_approval", "approved", "rejected", "declined", "cancelled", "expired"

• directionenumrequired

  one of "outgoing", "incoming", "other"

• requesterobjectrequired

  • idstring (uuid)required
  • namestringrequired
• peerobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• shiftobjectrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• peerShiftobject or nullrequired

  • idstring (uuid)required
  • datestringrequired
  • timestringrequired
• notestring | nullrequired
• reasonstring | nullrequired
• approvalRequestIdstring (uuid) or nullrequired
• createdAtstringrequired
• expiresAtstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found
• 409 conflict, shift_overlap, stale

GET/api/v1/scheduling/templates

Shift templates (active; add includeArchived=true for all)

Access

Permission rosters:read

Parameters

Name	In	Type	Required
includeArchived	query	enum	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • namestringrequired
  • codestringrequired
  • startTimestringrequired
  • endTimestringrequired
  • breakMinutesnumberrequired
  • paidMinutesnumberrequired
  • overnightbooleanrequired
  • locationIdstring (uuid) or nullrequired
  • locationNamestring | nullrequired
  • colourenumrequired

    one of "plain", "kuning", "biru", "oren", "ink"

  • archivedbooleanrequired
  • inUsebooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/scheduling/templates

Create a shift template

Access

Permission shift_templates:update

Request body

application/json, object, required

• namestringrequired

  min length 1 · max length 60

• codestringrequired

  min length 1 · max length 6

• startTimestringrequired
• endTimestringrequired
• breakMinutesintegerrequired

  min 0 · max 240

• locationIdstring (uuid) or nullrequired
• colourenumrequired

  one of "plain", "kuning", "biru", "oren", "ink"

Responses

201 Success. object

• idstring (uuid)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

PUT/api/v1/scheduling/templates/{id}

Update a shift template (existing shifts keep their times)

Access

Permission shift_templates:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• namestringrequired

  min length 1 · max length 60

• codestringrequired

  min length 1 · max length 6

• startTimestringrequired
• endTimestringrequired
• breakMinutesintegerrequired

  min 0 · max 240

• locationIdstring (uuid) or nullrequired
• colourenumrequired

  one of "plain", "kuning", "biru", "oren", "ink"

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

DELETE/api/v1/scheduling/templates/{id}

Delete a shift template no roster has used (otherwise archive it)

Access

Permission shift_templates:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 in_use

POST/api/v1/scheduling/templates/{id}/archive

Archive a shift template (shifts using it are kept)

Access

Permission shift_templates:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/scheduling/templates/{id}/restore

Restore an archived shift template

Access

Permission shift_templates:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict