Skip to content
XOS Developers

Update a shift

Crew module

PATCH/shifts/{id}shifts.update

A staffed crew block. A shift cannot end before it starts. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.

  • Requires the capability crew.shift.write.
  • OAuth scopes: crew.
  • Send If-Match with the ETag you read. A stale tag returns 412; a missing tag returns 428.
  • Error statuses: 400, 401, 404, 412, 422, 428, 429. Errors are RFC 9457 problem details.

Path and query parameters

shifts.update: Path and query parameters
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the shift.

Request body: ShiftUpdate

shifts.update: ShiftUpdate
FieldTypeRequiredDescription
record_idstring (uuid) | nullNoIdentifier of the Shift record.
role_codeRoleCode | nullNo
engagement_idstring (uuid) | nullNoIdentifier of the engagement.
starts_atstring (date-time)NoCall time.
ends_atstring (date-time)NoWrap time.
membership_idstring (uuid) | nullNoIdentifier of the membership of the person on the shift; null for external crew, who carry an engagement.
scope_node_idstring (uuid) | nullNoIdentifier of the scope node of the same project, such as the show.
time_zonestringNoIANA time zone the call and wrap times are shown in.Constraints: pattern ^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)*$
scheduled_break_minutesinteger | nullNoMeal break scheduled within the shift, in minutes.Constraints: range 0 to any
{
  "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "starts_at": "2026-10-08T14:30:00Z",
  "ends_at": "2026-10-08T14:30:00Z",
  "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "time_zone": "America/New_York",
  "scheduled_break_minutes": 30
}

Response 200: Shift

shifts.update: Shift
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the shift.
org_idstring (uuid)YesIdentifier of the owning organization, derived from the parent row and never accepted from the caller.
created_atstring (date-time)YesWhen the row was created.
created_bystring (uuid) | nullYesIdentifier of the person who created the row; null when a seed, platform or system process created it.
updated_atstring (date-time)YesWhen the row was last updated.
updated_bystring (uuid) | nullYesIdentifier of the person who last updated the row; null when a seed, platform or system process updated it.
project_idstring (uuid)YesIdentifier of the project.
record_idstring (uuid) | nullYesIdentifier of the Shift record.
role_codeRoleCode | nullYes
engagement_idstring (uuid) | nullYesIdentifier of the engagement.
starts_atstring (date-time)YesCall time.
ends_atstring (date-time)YesWrap time.
shift_state"Draft" | "Published" | "Accepted" | "Canceled"YesShift state.
membership_idstring (uuid) | nullYesIdentifier of the membership of the person on the shift; null for external crew, who carry an engagement.
scope_node_idstring (uuid) | nullYesIdentifier of the scope node of the same project, such as the show.
time_zonestringYesIANA time zone the call and wrap times are shown in.Constraints: pattern ^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)*$
scheduled_break_minutesinteger | nullYesMeal break scheduled within the shift, in minutes.Constraints: range 0 to any
{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "role_code": "5000.50.01",
  "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "starts_at": "2026-10-08T14:30:00Z",
  "ends_at": "2026-10-08T14:30:00Z",
  "shift_state": "Draft",
  "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "time_zone": "America/New_York",
  "scheduled_break_minutes": 30
}

Code samples

curl -X PATCH "$XOS_BASE_URL/shifts/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H 'If-Match: W/"etag-from-your-last-read"' \
  -H "Content-Type: application/json" \
  -d '{"record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","engagement_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","starts_at":"2026-10-08T14:30:00Z","ends_at":"2026-10-08T14:30:00Z","membership_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","scope_node_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","time_zone":"America/New_York","scheduled_break_minutes":30}'
const { data, etag } = await xos.shifts.update("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {
    "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "starts_at": "2026-10-08T14:30:00Z",
    "ends_at": "2026-10-08T14:30:00Z",
    "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "time_zone": "America/New_York",
    "scheduled_break_minutes": 30
  }, { ifMatch: etag });
response = xos.shifts.update("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {"record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30}, if_match=etag)
xos shifts update 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f --data '{"record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","engagement_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","starts_at":"2026-10-08T14:30:00Z","ends_at":"2026-10-08T14:30:00Z","membership_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","scope_node_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","time_zone":"America/New_York","scheduled_break_minutes":30}' --if-match auto