Create a template item

Platform module

POST/template-itemstemplateItems.create

An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422). Creates a template item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.

Requires the capability projects.template.write.
OAuth scopes: projects.
Send an Idempotency-Key header. A replay with the same key returns the original response.
Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.

Request body: TemplateItemCreate

templateItems.create: TemplateItemCreate
Field	Type	Required	Description
template_version_id	string (uuid)	Yes	Identifier of the template version.
item_kind	"Scope Node" \| "Record"	Yes	What the item creates.
sort_order	integer	Yes	Position in the version, 1 first.Constraints: range 1 to any
name	string	Yes	Scope node name, or record title.Constraints: length 1 to 200
scope_kind	"Standing Venue" \| "Show" \| null	No	For a scope node: Show or Standing Venue.
scope_code_suffix	string \| null	No	For a scope node: code after the project key.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
record_kind	string \| null	No	For a record: canon record kind.Constraints: length 1 to 50
xyz	"X" \| "Y" \| "Z" \| null	No	For a record: declared schema family tag.
phase_code	string \| null	No	For a record: canon phase.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
due_offset_days	integer \| null	No	For a record: due this many days after the project start; null for none.Constraints: range -3660 to 3660

{
  "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "item_kind": "Scope Node",
  "sort_order": 1,
  "name": "Opening Night",
  "scope_kind": "Show",
  "scope_code_suffix": "E02",
  "record_kind": "Inspection",
  "xyz": "X",
  "phase_code": "SCP",
  "due_offset_days": 3
}

Response 201: TemplateItem

templateItems.create: TemplateItem
Field	Type	Required	Description
id	string (uuid)	Yes	Identifier of the template item.
org_id	string (uuid)	Yes	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Yes	When the row was created.
created_by	string (uuid) \| null	Yes	Identifier of the person who created the row.
updated_at	string (date-time)	Yes	When the row was last updated.
updated_by	string (uuid) \| null	Yes	Identifier of the person who last updated the row.
template_version_id	string (uuid)	Yes	Identifier of the template version.
item_kind	"Scope Node" \| "Record"	Yes	What the item creates.
sort_order	integer	Yes	Position in the version, 1 first.Constraints: range 1 to any
name	string	Yes	Scope node name, or record title.Constraints: length 1 to 200
scope_kind	"Standing Venue" \| "Show" \| null	Yes	For a scope node: Show or Standing Venue.
scope_code_suffix	string \| null	Yes	For a scope node: code after the project key.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
record_kind	string \| null	Yes	For a record: canon record kind.Constraints: length 1 to 50
xyz	"X" \| "Y" \| "Z" \| null	Yes	For a record: declared schema family tag.
phase_code	string \| null	Yes	For a record: canon phase.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
due_offset_days	integer \| null	Yes	For a record: due this many days after the project start; null for none.Constraints: range -3660 to 3660

{
  "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",
  "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "item_kind": "Scope Node",
  "sort_order": 1,
  "name": "Opening Night",
  "scope_kind": "Show",
  "scope_code_suffix": "E02",
  "record_kind": "Inspection",
  "xyz": "X",
  "phase_code": "SCP",
  "due_offset_days": 3
}

Code samples

curl -X POST "$XOS_BASE_URL/template-items" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template_version_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","item_kind":"Scope Node","sort_order":1,"name":"Opening Night","scope_kind":"Show","scope_code_suffix":"E02","record_kind":"Inspection","xyz":"X","phase_code":"SCP","due_offset_days":3}'

const { data } = await xos.templateItems.create({
    "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "item_kind": "Scope Node",
    "sort_order": 1,
    "name": "Opening Night",
    "scope_kind": "Show",
    "scope_code_suffix": "E02",
    "record_kind": "Inspection",
    "xyz": "X",
    "phase_code": "SCP",
    "due_offset_days": 3
  });

response = xos.template_items.create({"template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_kind": "Scope Node", "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3})

xos template-items create --data '{"template_version_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","item_kind":"Scope Node","sort_order":1,"name":"Opening Night","scope_kind":"Show","scope_code_suffix":"E02","record_kind":"Inspection","xyz":"X","phase_code":"SCP","due_offset_days":3}'