Saltar al contenido
XOS para desarrolladores

Create a record

Módulo Work

POST/recordsrecords.create

A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. Creates a record. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.

  • Requiere la capacidad work.record.write.
  • Alcances de OAuth: work.
  • Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
  • Estados de error: 400, 401, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Cuerpo de la solicitud: RecordCreate

records.create: RecordCreate
CampoTipoObligatorioDescripción
record_kindRecordKindSíRecord kind from `xpms.dim_record_kind` (26 kinds, Section 3.10).Restricciones: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_subtypeRecordSubtypeNoKind-scoped record subtype from `xpms.dim_record_subtype`. A subtype of one kind cannot be stored on another.Restricciones: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
titlestringSíTitle, validated against the kind's title grammar on write.Restricciones: length 1 to 300
scope_node_idstring (uuid)SíIdentifier of the scope node.
phase_codePhaseCodeSíPhase code from `xpms.dim_phase`, ordered by gate ordinal.Restricciones: pattern ^[A-Z]{3}$
uridUridAtAnyGrainNoURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Restricciones: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
xyzXyzSíXYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.Restricciones: 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.Restricciones: length 1 to 20000
replan_reasonstring | nullNoReplan reason; required when Deferred.Restricciones: length 1 to 20000
external_visibilityarray of ExternalRoleTypeSíExternal role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.
{
  "record_kind": "Task",
  "title": "Install Main Stage Truss",
  "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "phase_code": "SCP",
  "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"
  ]
}

Respuesta 201: Record

records.create: Record
CampoTipoObligatorioDescripción
idstring (uuid)SíIdentifier of the record.
org_idstring (uuid)SíIdentifier of the owning organization, derived from the parent row and never accepted from the caller.
created_atstring (date-time)SíWhen the row was created.
created_bystring (uuid) | nullSíIdentifier of the person who created the row; null when a seed, platform or system process created it.
updated_atstring (date-time)SíWhen the row was last updated.
updated_bystring (uuid) | nullSíIdentifier of the person who last updated the row; null when a seed, platform or system process updated it.
record_keystringSíDisplay key issued by `next_sequence`.Restricciones: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
record_kindRecordKindSíRecord kind from `xpms.dim_record_kind` (26 kinds, Section 3.10).Restricciones: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_subtypeRecordSubtypeSíKind-scoped record subtype from `xpms.dim_record_subtype`. A subtype of one kind cannot be stored on another.Restricciones: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_classRecordClassSíRecord class from `xpms.dim_record_kind`, derived from the kind.Restricciones: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
record_stateRecordStateSíRecord state (Section 3.10). Blocked names its blocker, Deferred carries a replan reason, Canceled is retained.Restricciones: one of "Proposed", "Ready", "Scheduled", "Active", "Blocked", "In Review", "Complete", "Deferred", "Canceled"
titlestringSíTitle, validated against the kind's title grammar on write.Restricciones: length 1 to 300
scope_node_idstring (uuid)SíIdentifier of the scope node.
phase_codePhaseCodeSíPhase code from `xpms.dim_phase`, ordered by gate ordinal.Restricciones: pattern ^[A-Z]{3}$
uridUridAtAnyGrainSíURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Restricciones: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
xyzXyzSíXYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.Restricciones: pattern ^[XYZ]$
owner_party_idstring (uuid) | nullSíIdentifier of the owning person or organization.
accountable_party_idstring (uuid) | nullSíIdentifier of the accountable person or organization.
starts_atstring (date-time) | nullSíStart of the record window.
ends_atstring (date-time) | nullSíEnd of the record window.
due_atstring (date-time) | nullSíDue instant.
blocker_textstring | nullSíThe named blocker; required when Blocked.Restricciones: length 1 to 20000
replan_reasonstring | nullSíReplan reason; required when Deferred.Restricciones: length 1 to 20000
external_visibilityarray of ExternalRoleTypeSíExternal role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.
project_idstring (uuid)SíIdentifier of the project the record belongs to, derived from its scope node and never changed.
parent_record_idstring (uuid) | nullSíIdentifier of the summary record this record rolls up to, in the same project.
wbs_codestring | nullSíWork breakdown structure code, dot separated.Restricciones: pattern ^[0-9]+(\.[0-9]+)*$; length 1 to 50
descriptionstring | nullSíWhat the record involves, in sentence case.Restricciones: length 1 to 4000
sop_idstring (uuid) | nullSíIdentifier of the standard operating procedure that governs the work.
team_codeTeamId | nullSí
assignee_membership_idsarray of string (uuid)SíMemberships assigned to the record (app.record_assignments), oldest first.
progress_pctnumber | nullSíProgress of a task record, as a percentage.Restricciones: range 0 to 100
permit_identifierstring | nullSíPermit identifier the authority issued, on a permit record.Restricciones: length 1 to 200
inspection_result_enum_idstring (uuid) | nullSíIdentifier 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"
}

Ejemplos de código

curl -X POST "$XOS_BASE_URL/records" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"record_kind":"Task","title":"Install Main Stage Truss","scope_node_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","phase_code":"SCP","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"]}'
const { data } = await xos.records.create({
    "record_kind": "Task",
    "title": "Install Main Stage Truss",
    "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "phase_code": "SCP",
    "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"
    ]
  });
response = xos.records.create({"record_kind": "Task", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "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"]})
xos records create --data '{"record_kind":"Task","title":"Install Main Stage Truss","scope_node_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","phase_code":"SCP","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"]}'