Deliverable

One generic model carries the whole work tree. A node’s type decides which domain concept it represents, from an order at the top down to a single step. Search columns: name, identifier Standard CRUD applies. See standard endpoints.

These raw endpoints do not enforce the concept rules. A step under an order, or a stage node with no station, is accepted here and leaves a tree the app cannot display. For validated writes use the domain concepts endpoints.

Hierarchy in brief: the roots are order, route, overhead, and template-phase. The containers order, phase, and component nest freely and hold stage nodes. step and qcstep are leaves under a stage.

Fields

Every property the API returns for a deliverable.

Field	Type	Notes
`id`	UUID	Unique id. Generated on create unless you supply one. Server-managed.
`organizationId`	UUID	Your organization. Taken from the API key, never from the request body. Read-only.
`identifier`	string	Human-readable id, unique within your organization. Generated for you when you leave it out.
`name`	string	Display name. Required on create.
`isArchived`	boolean	Archived records are hidden from list results unless you ask for them. Set this to archive or restore the record. Defaults to `false`.
`archivedAt`	date-time \| null	When the record was archived. Set automatically when `isArchived` flips to `true`, and cleared on restore. Server-managed.
`archivedById`	UUID \| null	Who archived the record. Server-managed: a value you send is ignored.
`type`	enum	Which concept this node represents. One of `order` \| `route` \| `overhead` \| `template-phase` \| `phase` \| `component` \| `stage` \| `step` \| `qcstep` \| `group`. Required on create.
`quantity`	integer	How many of this node the work covers. Defaults to `1`.
`parentId`	UUID \| null	Node directly above this one.
`rootParentId`	UUID \| null	Root of this node’s tree. A root node points at itself.
`originTemplateId`	UUID \| null	Route or template this node was built from.
`cycleTimeSec`	integer	Cycle time per unit, in seconds. Defaults to `0`.
`durationSec`	integer	Total duration, in seconds. Defaults to `0`.
`peopleNum`	integer	How many people the node is planned for. Defaults to `1`.
`data`	object	Per-concept fields. Which keys apply depends on `type`: a stage node needs `stageId`, an order needs `projectId`, and so on. See the domain concepts guide for the full table.
`costCode`	string \| null	Cost code. Trimmed on write, and an empty string is rejected: send a non-empty string or `null`. Stored as a plain string and not validated against the cost code list.
`schedule`	object \| null	Scheduled window for the node. Present on `order` nodes only. Read-only.
`progress`	object \| null	Progress for the node. Present on `order` nodes only. Write it through the progress action endpoint rather than by patching this object. Read-only.
`computed`	object	Values BuildingSwell derives from the tree on every read. All read-only: anything you send here is ignored.
`alertType`	enum	Highest-priority alert state for the node. One of `on-hold` \| `late` \| `at-risk` \| `no-risk`. Derived on every read, and returned at the top level rather than inside `computed`. Read-only.
`alertTypeOrdinal`	integer	`alertType` as a sortable number: 0 no-risk, 1 at-risk, 2 late, 3 on-hold. Sort on this rather than on `alertType`, whose values are not alphabetical. Read-only.
`createdAt`	date-time	When the record was created. Server-managed.
`updatedAt`	date-time	When the record last changed. Server-managed.

`type` values

Ten concepts share this one model.

Value	Role	Description
`group`	grouping node	Groups cargo/work by `data.itemIds` without changing each member’s parent. Delivery trips can own a paired group.
`order`	root	Production ticket for a project. The only type that carries `schedule` and `progress`.
`route`	root	Reusable process blueprint, applied onto orders, phases, and components.
`overhead`	root	Indirect-labour bucket. A leaf, with time tracked through work sessions.
`template-phase`	root	Reusable phase header, mostly used inside routes.
`phase`	container	Groups work under an order, route, phase, or component. May link a route.
`component`	container	Quantity-bearing sub-assembly, nesting the same way a phase does.
`stage`	work node	A department work station. Must link a stage through `data.stageId`.
`step`	leaf	A unit of work. Must sit under a `stage`.
`qcstep`	leaf	A QC gate. Must sit under a `stage`, and needs `data.qcTemplateId`.

Custom property values

Orders store catalog-defined values at data.properties.<key>. Nonempty property maps merge by key; {} or null clears all values. The rollout flag, value types, and query examples are covered in custom properties.

`schedule`

Field	Type	Notes
`startDate`	date-time	Scheduled start.
`endDate`	date-time	Scheduled finish.

This is the stored shape, returned by GET. You do not write it directly: it is the result of the schedule action endpoints, whose request bodies use a different shape with epoch-second times.

`progress`

Field	Type	Notes
`status`	enum	Where the work stands right now. One of `waiting` \| `todo` \| `wip` \| `rework` \| `on-hold` \| `done`.
`completed`	number	Quantity finished. Defaults to `0`.
`wip`	number	Quantity in progress. Defaults to `0`.
`percentage`	number	Percent complete, 0 to 100. Defaults to `0`.
`startedAt`	date-time \| null	When work first started.
`completedAt`	date-time \| null	When the node reached `done`.
`hasBeenReworked`	boolean	`true` once the node has ever been set to `rework`. Server-managed, and it stays `true` after the status changes again. Defaults to `false`.
`updatedById`	UUID \| null	Who last changed progress. Server-managed, and `null` for transitions into `waiting`.
`updatedAt`	date-time \| null	When progress last changed. Server-managed, and `null` for transitions into `waiting`.

hasBeenReworked, updatedById, and updatedAt are server-managed. hasBeenReworked flips to true the first time a node enters rework and stays true afterwards, so it tells you whether rework ever happened rather than whether it is happening now.

`computed`

All read-only. BuildingSwell derives these from the tree on every read, so anything you send is ignored.

Field	Type	Notes
`groupIds`	UUID[]	IDs of group deliverables containing this node. Read-only reverse membership derived from group `data.itemIds`.
`rootType`	enum \| null	`type` of the root node of this tree. One of `order` \| `route` \| `overhead` \| `template-phase` \| `phase` \| `component` \| `stage` \| `step` \| `qcstep` \| `group`.
`fullName`	string[]	Name breadcrumb from the root down to this node.
`fullPath`	UUID[]	Id breadcrumb from the root down to this node.
`shopId`	UUID \| null	Department that applies to this node, inherited from the nearest ancestor when the node does not set one. `null` means cross-department.
`phasesPath`	string[]	Phase names in this node’s ancestry.
`phase`	string \| null	Nearest phase name above this node.
`currentChildren`	object[]	Summary of the node’s direct children.
`containedStageIds`	(UUID \| null)[]	Every station anywhere beneath this node.
`containedPhaseNames`	string[]	Every phase name anywhere beneath this node.
`containedCurrentStageIds`	(UUID \| null)[]	Stations beneath this node that sit on the active work frontier.
`containedCurrentPhaseNames`	string[]	Phase names beneath this node that sit on the active work frontier.
`currentStageIds`	UUID[]	Stations on this node’s own active work frontier. Filter it with the `jinco` operator.
`currentPhaseNames`	string[]	Phase names on this node’s own active work frontier.
`combinedWorkerIds`	UUID[]	Everyone assigned anywhere beneath this node.
`combinedTagIds`	string[]	Every tag anywhere beneath this node.
`workerIds`	UUID[]	People assigned directly to this node.
`tags`	string[]	Tags on this node itself.
`isLeaf`	boolean	`true` when the node has no children. Defaults to `true`.
`projectId`	UUID \| null	Project this tree belongs to.
`date`	string \| null	Effective date for the node.
`isAtRisk`	boolean	`true` when the node is trending late. Defaults to `false`.
`isLate`	boolean	`true` when the node has missed its date. Defaults to `false`.
`effectiveDueDate`	string \| null	Due date that applies, whether set here or inherited.
`effectiveDueDateIsInherited`	boolean	`true` when the due date comes from an ancestor. Defaults to `false`.
`effectiveDueDateIsLate`	boolean	`true` when the effective due date has passed. Defaults to `false`.
`hasReworkedStages`	boolean	`true` when any stage beneath this node has been reworked. Defaults to `false`.

alertType and alertTypeOrdinal are derived the same way but are returned at the top level of the record, not inside computed. They are in the field table above.

Extra endpoints

Read a whole subtree

GET /deliverable/<id>/hierarchy

Returns { "values": Deliverable[], "totalCount": number } with the node and every node beneath it.

Group by a domain dimension

POST /deliverable/groups

{ "groupBy": "project" }

groupBy takes project, phase, stage, people, root, or tags. Use this when you want counts by something the model does not store as a plain column; POST /deliverable/group-and-count covers raw columns.

Reorder under a root

POST /deliverable/reorder

{
  "rootParentId": "<uuid>",
  "orderedDeliverableIds": ["<uuid1>", "<uuid2>"]
}

The list becomes the new sequence, and the dependency links are rewritten to match. Responds 204 with no body.

Crew time

POST /deliverable/crew-time

{ "deliverableId": ["<uuid>"], "breakdown": false }

Returns a map keyed by deliverable id. Set breakdown to split the totals out per person and station.

GET /deliverable/crew-time is deprecated. Repeating deliverableId in the query string exceeds URL length limits once you ask about many orders at once. Use the POST form above.

Schedule a node

POST /deliverable/root/<rootId>/schedule/<id>

The body is an action union keyed on type, not { startDate, endDate }. Times are epoch seconds, and you send only one of newStart or newFinish: the engine derives the other from duration and dependencies.

// Initial placement
{ "type": "schedule", "newStart": 1772323200 }

// Move without changing duration
{ "type": "drag", "newFinish": 1773532800 }

// Change duration, anchored at start or finish
{ "type": "shrink", "newDuration": 604800, "newStart": 1772323200 }
{ "type": "expand", "newDuration": 1814400, "newFinish": 1773532800 }

// Recompute from dependencies
{ "type": "reschedule" }

Responds 204 with no body. Re-read the node with GET /deliverable/{id} to see the resulting schedule.

Schedule in a batch

POST /deliverable/schedule/batch

[
  {
    "rootParentId": "<uuid>",
    "targetId": "<uuid>",
    "action": { "type": "drag", "newStart": 1772323200 }
  }
]

Same action union, wrapped per item. Responds 204 with no body.

Update progress

POST /deliverable/root/<rootId>/progress/<id>

Another action union, rather than a patch of the progress object:

{ "type": "complete" }
{ "type": "uncomplete", "quantity": 5 }
{ "type": "send-ahead", "quantity": 3 }
{ "type": "rework" }
{ "type": "put-on-hold" }
{ "type": "resume-work" }
{ "type": "set-percentage", "percentage": 60 }

set-percentage is not allowed on qcstep nodes. Responds 200 with { "kickedWorkers": [...] }, the ids of anyone whose open work sessions and daily-plan assignments were stopped because their deliverable reached done. It does not return the updated node, so re-read it if you need the new progress.

To show someone the consequences of a destructive action such as rework before committing, call POST /concepts/root/{rootId}/progress/{id}/plan first. It computes the effect and writes nothing.

What you can write

Everything else in the table above is set by BuildingSwell.

Field	On create	On update
`identifier`	Optional	Yes
`name`	Required	Yes
`isArchived`	Optional	Yes
`type`	Required	Yes
`quantity`	Optional	Yes
`parentId`	Optional	Yes
`rootParentId`	Optional	Yes
`originTemplateId`	Optional	Yes
`cycleTimeSec`	Optional	Yes
`durationSec`	Optional	Yes
`peopleNum`	Optional	Yes
`data`	Optional	Yes
`costCode`	Optional	Yes

Archive and restore

There is no separate archive endpoint. Flip isArchived with a PATCH, and BuildingSwell handles the rest.

# Archive
PATCH /deliverable/<id>
{ "isArchived": true }

# Restore
PATCH /deliverable/<id>
{ "isArchived": false }

When you archive:

identifier gets an - (archived <timestamp>) suffix, where <timestamp> is the archive time in epoch milliseconds. Match it with a pattern, not a literal string.
archivedAt is stamped with the current time.
Archiving cascades to every node beneath the one you archive, and then re-rolls the parent’s times and progress, because removing the last incomplete step can make a stage done. Restoring cascades the same way and re-rolls again.

When you restore, the suffix comes off, and a colliding identifier is given the next free variant. Archived records drop out of list results by default. Ask for them with an explicit filter:

GET /deliverable?isArchived=true

Deleting

DELETE /deliverable/{id} is destructive.Permanently removes the node and every node beneath it. This is not the archive operation and it cannot be undone. Prefer PATCH /deliverable/{id} with { "isArchived": true }, which cascades the same way and is reversible.Before the rows go, BuildingSwell relinks what pointed at them so you do not silently lose time or QC history:

Work sessions and QC entries on any deleted node are moved onto the nearest surviving ancestor.
Dependency links touching any deleted node are removed with it.
When there is no surviving ancestor, which is the case when you delete a root order, the call is rejected with 400 if the subtree has work sessions or QC entries. Archive it instead.

See archiving and deleting for the full picture across resources.

Getting started

Core concepts

Resources

Materials and inventory

Delivery

Organization lists

Domain concepts

Examples

Fields

`type` values

Custom property values

`schedule`

`progress`

`computed`

Extra endpoints

Read a whole subtree

Group by a domain dimension

Reorder under a root

Crew time

Schedule a node

Schedule in a batch

Update progress

What you can write

Archive and restore

Deleting

​Fields

​type values

​Custom property values

​schedule

​progress

​computed

​Extra endpoints

​Read a whole subtree

​Group by a domain dimension

​Reorder under a root

​Crew time

​Schedule a node

​Schedule in a batch

​Update progress

​What you can write

​Archive and restore

​Deleting

Fields

`type` values

Custom property values

`schedule`

`progress`

`computed`

Extra endpoints

Read a whole subtree

Group by a domain dimension

Reorder under a root

Crew time

Schedule a node

Schedule in a batch

Update progress

What you can write

Archive and restore

Deleting