Skip to content
XOS Developers

Update a record

Work module

PATCH/records/{id}records.update

A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. 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 work.record.write.
  • OAuth scopes: work.
  • 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

records.update: Path and query parameters
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the record.

Request body: RecordUpdate

records.update: RecordUpdate
FieldTypeRequiredDescription
record_subtypeRecordSubtypeNoKind-scoped record subtype from `xpms.dim_record_subtype`. A subtype of one kind cannot be stored on another.Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
titlestringNoTitle, validated against the kind's title grammar on write.Constraints: length 1 to 300
scope_node_idstring (uuid)NoIdentifier of the scope node.
phase_codePhaseCodeNoPhase code from `xpms.dim_phase`, ordered by gate ordinal.Constraints: pattern ^[A-Z]{3}$
uridUridAtAnyGrainNoURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Constraints: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
xyzXyzNoXYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.Constraints: pattern ^[XYZ]$
owner_party_idstring (uuid) | nullNoIdentifier of the owning person or organization.
accountable_party_idstring (uuid) | nullNoIdentifier of the accountable person or organization.
starts_atstring (date-time) | nullNoStart of the record window.
ends_atstring (date-time) | nullNoEnd of the record window.
due_atstring (date-time) | nullNoDue instant.
blocker_textstring | nullNoThe named blocker; required when Blocked.Constraints: length 1 to 20000
replan_reasonstring | nullNoReplan reason; required when Deferred.Constraints: length 1 to 20000
external_visibilityarray of ExternalRoleTypeNoExternal role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.
parent_record_idstring (uuid) | nullNoIdentifier of the summary record this record rolls up to, in the same project.
wbs_codestring | nullNoWork breakdown structure code, dot separated.Constraints: pattern ^[0-9]+(\.[0-9]+)*$; length 1 to 50
descriptionstring | nullNoWhat the record involves, in sentence case.Constraints: length 1 to 4000
sop_idstring (uuid) | nullNoIdentifier of the standard operating procedure that governs the work.
team_codeTeamId | nullNo
{
  "title": "Install Main Stage Truss",
  "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "starts_at": "2026-10-08T14:30:00Z",
  "ends_at": "2026-10-08T14:30:00Z",
  "due_at": "2026-10-08T14:30:00Z",
  "blocker_text": "Waiting on the rigging plot.",
  "replan_reason": "Moved to the second weekend.",
  "external_visibility": [
    "Vendor"
  ],
  "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "wbs_code": "1.2.1",
  "description": "Rig the downstage truss.",
  "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}

Response 200: Record

records.update: Record
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the record.
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.
record_keystringYesDisplay key issued by `next_sequence`.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
record_kindRecordKindYesRecord kind from `xpms.dim_record_kind` (26 kinds, Section 3.10).Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_subtypeRecordSubtypeYesKind-scoped record subtype from `xpms.dim_record_subtype`. A subtype of one kind cannot be stored on another.Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_classRecordClassYesRecord class from `xpms.dim_record_kind`, derived from the kind.Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_stateRecordStateYesRecord state (Section 3.10). Blocked names its blocker, Deferred carries a replan reason, Canceled is retained.Constraints: one of "Proposed", "Ready", "Scheduled", "Active", "Blocked", "In Review", "Complete", "Deferred", "Canceled"
titlestringYesTitle, validated against the kind's title grammar on write.Constraints: length 1 to 300
scope_node_idstring (uuid)YesIdentifier of the scope node.
phase_codePhaseCodeYesPhase code from `xpms.dim_phase`, ordered by gate ordinal.Constraints: pattern ^[A-Z]{3}$
uridUridAtAnyGrainYesURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Constraints: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
xyzXyzYesXYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.Constraints: pattern ^[XYZ]$
owner_party_idstring (uuid) | nullYesIdentifier of the owning person or organization.
accountable_party_idstring (uuid) | nullYesIdentifier of the accountable person or organization.
starts_atstring (date-time) | nullYesStart of the record window.
ends_atstring (date-time) | nullYesEnd of the record window.
due_atstring (date-time) | nullYesDue instant.
blocker_textstring | nullYesThe named blocker; required when Blocked.Constraints: length 1 to 20000
replan_reasonstring | nullYesReplan reason; required when Deferred.Constraints: length 1 to 20000
external_visibilityarray of ExternalRoleTypeYesExternal role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.
project_idstring (uuid)YesIdentifier of the project the record belongs to, derived from its scope node and never changed.
parent_record_idstring (uuid) | nullYesIdentifier of the summary record this record rolls up to, in the same project.
wbs_codestring | nullYesWork breakdown structure code, dot separated.Constraints: pattern ^[0-9]+(\.[0-9]+)*$; length 1 to 50
descriptionstring | nullYesWhat the record involves, in sentence case.Constraints: length 1 to 4000
sop_idstring (uuid) | nullYesIdentifier of the standard operating procedure that governs the work.
team_codeTeamId | nullYes
assignee_membership_idsarray of string (uuid)YesMemberships assigned to the record (app.record_assignments), oldest first.
progress_pctnumber | nullYesProgress of a task record, as a percentage.Constraints: range 0 to 100
permit_identifierstring | nullYesPermit identifier the authority issued, on a permit record.Constraints: length 1 to 200
inspection_result_enum_idstring (uuid) | nullYesIdentifier of the Inspection Result enumeration row (Standard Library) of an inspection record.
{
  "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",
  "record_key": "NWL-24-118",
  "record_kind": "Task",
  "record_subtype": "Design",
  "record_class": "Work",
  "record_state": "Scheduled",
  "title": "Install Main Stage Truss",
  "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "phase_code": "SCP",
  "urid": "4000.01",
  "xyz": "X",
  "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "starts_at": "2026-10-08T14:30:00Z",
  "ends_at": "2026-10-08T14:30:00Z",
  "due_at": "2026-10-08T14:30:00Z",
  "blocker_text": "Waiting on the rigging plot.",
  "replan_reason": "Moved to the second weekend.",
  "external_visibility": [
    "Vendor"
  ],
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "wbs_code": "1.2.1",
  "description": "Rig the downstage truss.",
  "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "team_code": "4000-T01",
  "assignee_membership_ids": [
    "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
  ],
  "progress_pct": 40,
  "permit_identifier": "BP-2027-0611",
  "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}

Code samples

curl -X PATCH "$XOS_BASE_URL/records/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 '{"title":"Install Main Stage Truss","scope_node_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","owner_party_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","accountable_party_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","starts_at":"2026-10-08T14:30:00Z","ends_at":"2026-10-08T14:30:00Z","due_at":"2026-10-08T14:30:00Z","blocker_text":"Waiting on the rigging plot.","replan_reason":"Moved to the second weekend.","external_visibility":["Vendor"],"parent_record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","wbs_code":"1.2.1","description":"Rig the downstage truss.","sop_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'
const { data, etag } = await xos.records.update("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {
    "title": "Install Main Stage Truss",
    "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "starts_at": "2026-10-08T14:30:00Z",
    "ends_at": "2026-10-08T14:30:00Z",
    "due_at": "2026-10-08T14:30:00Z",
    "blocker_text": "Waiting on the rigging plot.",
    "replan_reason": "Moved to the second weekend.",
    "external_visibility": [
      "Vendor"
    ],
    "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "wbs_code": "1.2.1",
    "description": "Rig the downstage truss.",
    "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
  }, { ifMatch: etag });
response = xos.records.update("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {"title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}, if_match=etag)
xos records update 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f --data '{"title":"Install Main Stage Truss","scope_node_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","owner_party_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","accountable_party_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","starts_at":"2026-10-08T14:30:00Z","ends_at":"2026-10-08T14:30:00Z","due_at":"2026-10-08T14:30:00Z","blocker_text":"Waiting on the rigging plot.","replan_reason":"Moved to the second weekend.","external_visibility":["Vendor"],"parent_record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","wbs_code":"1.2.1","description":"Rig the downstage truss.","sop_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}' --if-match auto