Deliverable

Central, generic resource: one model implements nine domain concepts via its type field. The raw deliverable endpoints below are low-level and do not enforce concept rules (valid nesting, required fields, stage linkage, Department scoping). For concept-aware, validated work — and to learn how the concepts fit together — use the Domain concepts endpoints. Hierarchy in brief (see the concepts section for the full grammar): roots are order, route, overhead, template-phase; the containers order/phase/component nest freely and hold stage nodes; step and qcstep are leaves under a stage. Import/Export: ✓ — see import and export Search columns: name, identifier Standard CRUD applies. See standard endpoints.

Fields

Field	Type	Notes
`id`	UUID	Auto-generated
`organizationId`	UUID	From API key
`identifier`	string	Auto-generated
`name`	string	Required
`type`	string	See types below
`quantity`	integer	Default `1`
`parentId`	UUID \| null	Parent deliverable
`rootParentId`	UUID \| null	Root of hierarchy
`originTemplateId`	UUID \| null	Template it was created from
`cycleTimeSec`	integer	Cycle time in seconds
`durationSec`	integer	Duration in seconds
`peopleNum`	integer	Default `1`
`data`	object	Extensible key-value store
`costCode`	string \| null
`schedule`	object \| null	See below
`progress`	object \| null	See below
`computed`	object	Read-only, see below
`isArchived`	boolean	Default `false`
`createdAt`	date	Auto-generated
`updatedAt`	date	Auto-generated

`type` values

Value	Role	Description
`order`	root	Production ticket for a project. The only type with `schedule` + `progress`.
`route`	root	Reusable process blueprint, applied onto orders/phases/components.
`overhead`	root	Indirect-labour bucket (leaf); time is tracked via work sessions.
`template-phase`	root	Reusable phase header, applied to a phase (mostly used inside routes).
`phase`	container	Groups work under an order/route/phase/component; may link a route.
`component`	container	Quantity-bearing sub-assembly; same nesting as a phase.
`stage`	work node	A Department work-station. Must link a stage via `data.stageId`.
`step`	leaf	A unit of work; must be under a `stage`.
`qcstep`	leaf	A QC gate; must be under a `stage`; needs `data.qcTemplateId`.

`schedule` shape

{
  "startDate": "2024-03-01T00:00:00.000Z",
  "endDate": "2024-03-15T00:00:00.000Z"
}

This is the shape stored on the record and returned by GET. You don’t write it directly — it’s an effect of the schedule action endpoints below, whose request bodies use a different shape (an action union with epoch-second times, not startDate/endDate).

`progress` shape

{
  "status": "wip",
  "completed": 10,
  "wip": 5,
  "percentage": 60,
  "startedAt": "2024-03-01T08:00:00.000Z",
  "completedAt": null,
  "hasBeenReworked": false,
  "updatedById": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "updatedAt": "2024-03-02T10:00:00.000Z"
}

Field	Type	Notes
`status`	string	Current progress status
`completed`	number	Completed quantity
`wip`	number	Work-in-progress quantity
`percentage`	number	Completion percentage (0–100)
`startedAt`	date \| null	When work first started
`completedAt`	date \| null	When the deliverable reached `done`
`hasBeenReworked`	boolean	`true` if the deliverable has ever been set to `rework` status. Immutable once set to `true`.
`updatedById`	UUID \| null	ID of the user who last updated progress (auto-populated; `null` for `waiting` transitions)
`updatedAt`	date \| null	Timestamp of the last progress update (auto-populated; `null` for `waiting` transitions)

hasBeenReworked, updatedById, and updatedAt are server-managed — you do not need to supply them. hasBeenReworked is set automatically to true when a deliverable enters rework status and stays true even after the status subsequently changes.

`computed` shape (read-only)

Field	Type	Description
`rootType`	string \| null	`type` of the root deliverable in the hierarchy
`fullName`	string[]	Name breadcrumb from root
`fullPath`	string[]	ID breadcrumb from root
`shopId`	UUID \| null	Resolved shop
`phasesPath`	string[]	Phase names in ancestry
`phase`	string \| null	Nearest phase name
`currentChildren`	object[]	Direct children summary
`containedStageIds`	UUID[]	All stage IDs anywhere under this node
`containedPhaseNames`	string[]	All phase names anywhere under this node
`currentStageIds`	UUID[]	Stage IDs on the node’s current (active) work frontier; filter with `jinco`
`currentPhaseNames`	string[]	Phase names on the current work frontier
`combinedWorkerIds`	UUID[]	All worker IDs assigned anywhere under this node
`combinedTagIds`	string[]	All tag IDs anywhere under this node
`isLeaf`	boolean	`true` if no children
`workerIds`	UUID[]	Workers directly assigned to this deliverable
`tags`	string[]	Tags on this deliverable
`projectId`	UUID \| null	Project this belongs to
`date`	string \| null	Effective date
`isAtRisk`	boolean
`isLate`	boolean
`effectiveDueDate`	string \| null
`effectiveDueDateIsInherited`	boolean
`effectiveDueDateIsLate`	boolean
`alertType`	`on-hold` \| `late` \| `at-risk` \| `no-risk`	Highest-priority alert state
`alertTypeOrdinal`	integer	Numeric ordinal for `alertType` (0 = no-risk, 1 = at-risk, 2 = late, 3 = on-hold)

Extra endpoints

Hierarchy

Returns all deliverables in the subtree:

GET /deliverable/:id/hierarchy

Response: { "values": Deliverable[], "totalCount": number }

Groups

Group deliverables by a semantic dimension:

POST /deliverable/groups

{ "groupBy": "project" }

groupBy values: project | stage | people | root | tags

Reorder

Set dependency order under a root:

POST /deliverable/reorder

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

Response: 204 No Content

Crew time

GET /deliverable/crew-time?deliverableId=<uuid>

Response: { "<deliverableId>": { ... } }

Schedule a deliverable

The body is an action union (type discriminates the shape), not {startDate, endDate}. Times are epoch seconds (newStart / newFinish), not ISO strings — only one of the two is required per call, the engine derives the other from duration/dependencies.

POST /deliverable/root/:rootId/schedule/:id

// type: "schedule" — initial placement
{ "type": "schedule", "newStart": 1709251200 }

// type: "drag" — move without changing duration
{ "type": "drag", "newFinish": 1710460800 }

// type: "shrink" / "expand" — change duration, anchored at start or finish
{ "type": "shrink", "newDuration": 604800, "newStart": 1709251200 }
{ "type": "expand", "newDuration": 1814400, "newFinish": 1710460800 }

// type: "reschedule" — recompute from dependencies, no extra fields
{ "type": "reschedule" }

Response: 204 No Content — re-fetch the deliverable (GET /deliverable/:id) to see the resulting schedule.

Batch schedule

Same action union as above, wrapped with rootParentId/targetId per item:

POST /deliverable/schedule/batch

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

Response: 204 No Content.

Update progress

The body is an action union (type discriminates the shape), not {status, completed, wip}:

POST /deliverable/root/:rootId/progress/:id

// type: "complete" — no extra fields
{ "type": "complete" }

// type: "uncomplete" — revert a completed quantity back to wip
{ "type": "uncomplete", "quantity": 5 }

// type: "send-ahead" — partially complete ahead of dependencies
{ "type": "send-ahead", "quantity": 3 }

// type: "rework" — no extra fields
{ "type": "rework" }

// type: "put-on-hold" / "resume-work" — no extra fields
{ "type": "put-on-hold" }
{ "type": "resume-work" }

// type: "set-percentage" — not allowed on qcstep nodes
{ "type": "set-percentage", "percentage": 60 }

Response: 200 with { "kickedWorkers": [...] } — the IDs of any workers whose in-progress work sessions/plans were stopped because their deliverable reached done. It does not return the updated deliverable; re-fetch it separately if you need the new progress.

Getting started

Core concepts

Resources

Domain concepts

Examples

Fields

`type` values

`schedule` shape

`progress` shape

`computed` shape (read-only)

Extra endpoints

Hierarchy

Groups

Reorder

Crew time

Schedule a deliverable

Batch schedule

Update progress

​Fields

​type values

​schedule shape

​progress shape

​computed shape (read-only)

​Extra endpoints

​Hierarchy

​Groups

​Reorder

​Crew time

​Schedule a deliverable

​Batch schedule

​Update progress

Fields

`type` values

`schedule` shape

`progress` shape

`computed` shape (read-only)

Extra endpoints

Hierarchy

Groups

Reorder

Crew time

Schedule a deliverable

Batch schedule

Update progress