Stage

A stage is a shop station you reuse across jobs, such as Welding or Paint. It belongs to one department (shopId). Deliverable stage nodes point at one through data.stageId. See domain concepts for how that linkage works. Search columns: name Standard CRUD applies. See standard endpoints.

Fields

Every property the API returns for a stage.

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.
`name`	string	Station name, for example `Welding`. Required on create.
`shopId`	UUID	Department the station belongs to. Required on create.
`description`	string \| null	What happens at this station.
`maxOrderCapacity`	integer	How many orders the station can hold at once. Zero or greater. Required on create.
`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.
`archivedAt`	date-time \| null	Archive time, cleared on restore. Server-managed.
`isArchived`	boolean	Archived stations are hidden from list results unless you ask for them. Defaults to `false`.
`createdAt`	date-time	When the record was created. Server-managed.
`updatedAt`	date-time	When the record last changed. Server-managed.

Stages carry no identifier. They are keyed by name within a department. Both isArchived and archivedAt describe archive state.

Capacity

maxOrderCapacity is how many orders the station holds at once. Planning uses it to tell you when a station is oversubscribed, so a value of 0 means the station takes no work rather than unlimited work.

What you can write

Everything else in the table above is set by BuildingSwell.

Field	On create	On update
`name`	Required	Yes
`shopId`	Required	Yes
`description`	Optional	Yes
`maxOrderCapacity`	Required	Yes
`costCode`	Optional	Yes
`isArchived`	Optional	Yes

Deleting

DELETE /stage/{id} is destructive.Permanently removes the station. This is not the archive operation and it cannot be undone.In practice this fails with 409 whenever a team or a route step is still assigned to the station, because those links are ON DELETE NO ACTION. Reassign them first, or archive the station instead.When the delete does go through, deliverable stage nodes are not protected: they point at a station through data.stageId, which is a JSON value rather than a foreign key, so those nodes keep an id that no longer resolves. Any QC entry referencing the station has its stageId set to null.

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

Capacity

What you can write

Deleting