Domain concepts

The deliverable resource is deliberately generic: one model carries nine domain concepts, and its type field decides which one a node is. That keeps the model simple, and it means the raw endpoints will accept a tree that makes no sense. The /concepts endpoints sit on top of the same data and enforce the rules. They speak the domain language, and they check what the raw endpoints do not: valid nesting, the fields each concept requires, station linkage, and department scoping. Prefer these for writes. Reads are the same either way, so use GET /deliverable with its filters and joins when you are reading.

A department is a shop, carried as data.shopId. null means the node applies across departments.

The nesting grammar

order          (root)  → phase | component | stage
route          (root)  → phase | component | stage          # reusable template
overhead       (root)  → (leaf)
template-phase (root)  → (leaf)
phase          → phase | component | stage                  # containers nest freely
component      → phase | component | stage                  #   any depth, either way
stage          → step | qcstep                              # steps and QC steps only
step           → (leaf)                                     # must be under a stage
qcstep         → (leaf)                                     # must be under a stage

POST /concepts/deliverables rejects anything outside this grammar with a 400, so a step under an order fails here rather than becoming a node the app cannot display. You do not have to hard-code this. GET /concepts returns the same grammar as data, which lets you validate a payload before you send it.

Concept reference

* marks a field that is required in data. Every node also carries the base deliverable columns: identifier, quantity, schedule, progress, computed, and the rest.

Concept	Identifier	Required `data`	Other `data`	Notes
`order`	`ORD-` (auto)	`projectId*`	`dueDate`, `notes`, `tags`, `workerIds`, `workOrder`, `shopId`	The only type carrying `schedule` and `progress`.
`route`	`RUT-` (auto)	none	`description`, `shopId`, `tags`, `workerIds`	A `null` `shopId` makes it a cross-department process route.
`overhead`	auto	`category*`	`shopId`	A leaf. Time is tracked through work sessions.
`template-phase`	auto	none	`shopId`, `workerIds`, `isProduction`	Reusable phase header.
`phase`	yours or auto	none	`dueDate`, `shopId`, `isProduction`, `linkedRouteId`, `position`, `tags`, `workerIds`	`linkedRouteId` is a sub-route applied when the parent is applied.
`component`	yours or auto	none	`dueDate`, `linkedRouteId`, `tags`, `workerIds`	Quantity-bearing sub-assembly.
`stage`	yours or auto	`stageId*`	`dueDate`, `position`, `tags`, `workerIds`	Links a stage. See below.
`step`	auto	none	none	Uses the top-level `cycleTimeSec`, `peopleNum`, and `quantity`.
`qcstep`	auto	`qcTemplateId*`	none	A QC gate.

You can set identifier yourself on any type. Leave it out and one is generated.

Stage nodes and their station

A stage node always carries data.stageId pointing at a stage, which is a reusable station scoped to one department. On create, three things can happen:

You send data.stageId. It is validated: the station has to exist, and its department has to match the node’s resolved department.
You leave it out. The layer finds or creates a station named after the node, in the node’s department, and links it. You get sensible stations without having to pre-create them.
You leave it out and no department can be resolved. The request is rejected. A station belongs to a department, so without one there is nothing to search or create in.

A node’s effective department is its own data.shopId, or the nearest ancestor’s if it has none. Either way it is exposed as computed.shopId.

Applying routes

Setting originTemplateId on create, or data.linkedRouteId on a container, applies that route’s structure underneath the node. Routes compose recursively and are cycle-protected, so a route that references itself through another route is rejected rather than expanding forever. Applying a department-scoped route overrides the target’s department.

Endpoints

Method and path	What it does
`GET /concepts`	The concept registry as data: every concept with `kind`, `allowedParents`, `allowedChildren`, `requires`, `dataFields`, `identifier`, `hasSchedule`, `hasProgress`, and `departmentScoped`. Returns `{ "concepts": [...] }`.
`GET /concepts/orders/{id}/context`	One order’s standing: `{ orderId, order, rollup, blocked }`. `rollup` holds `nodeCount`, `byType`, `byStatus`, `edges`, `late`, `atRisk`, `onHold`, `currentPhases`, and `currentStageIds`. `blockedLimit` defaults to 25.
`GET /concepts/routes/{id}`	A route with the same tree rollup.
`GET /concepts/stage-masters?departmentId=<shopId>`	Stations, optionally narrowed to one department.
`POST /concepts/deliverables`	Create a node with validation. `201` with the node.
`PATCH /concepts/deliverables/{id}`	Change `name`, `costCode`, or `data` with the same validation.
`POST /concepts/orders/from-route`	Create an order for a project from a route, bringing the route’s structure with it.
`POST /concepts/deliverables/{id}/apply-route`	Apply a route under an existing `order`, `phase`, or `component`.
`POST /concepts/root/{rootId}/progress/{id}/plan`	Work out what a progress action would do, without writing.
`POST /concepts/root/{rootId}/progress/{id}/apply`	Apply it, cascading through the tree, stopping work sessions, and clearing daily-plan assignments for nodes that become `done`.

Call /plan before /apply for anything destructive, such as rework. It returns the effect and writes nothing, which gives you something concrete to show someone before they commit.

Concept writes still respect your key’s record permissions. Creating a station needs stage:create, and the flow edges a route brings with it need deliverable_dependency:create.

Starting an order from a route

This is the common path for work that follows a standard process:

curl -X POST "https://app.buildingswell.com/api/v2/concepts/orders/from-route" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{
        "routeId": "<routeId>",
        "projectId": "<projectId>",
        "name": "Warehouse A, run 3",
        "dueDate": "2026-04-15T00:00:00.000Z"
      }'

You get back the new order’s context, so you can see the tree the route produced without a second read.

Getting started

Core concepts

Resources

Materials and inventory

Delivery

Organization lists

Examples

Domain concepts

The nesting grammar

Concept reference

Stage nodes and their station

Applying routes

Endpoints

Starting an order from a route

​The nesting grammar

​Concept reference

​Stage nodes and their station

​Applying routes

​Endpoints

​Starting an order from a route

The nesting grammar

Concept reference

Stage nodes and their station

Applying routes

Endpoints

Starting an order from a route