Relay reference

Stage types

A process is an ordered list of stages, and every stage is one of these. The set is closed: Relay refuses a type it does not know rather than guessing.

Type	Behaviour	Counts units	Pays
task	general task with configured fields
claim_task	general task claimed before work
handover	general counted handover	yes
completed	terminal, no invoice required
pickup	claimed before it is worked	yes
workshop	outside the building, no accounts	yes
intake	worked in place	yes
definition	worked in place
piecework	worked in place		yes
washer_batch	worked in place
dryer_batch	worked in place
frost	worked in place
press	worked in place		yes
exit	worked in place	yes
invoiced	terminal — reaching it closes the lot

Exactly one terminal stage, and it must be last.

A stage carries a name (yours), a role (the acting_tag), an optional SLA in days, and an optional condition that makes some lots skip it.

Configured fields and conditions

Stage fields is an array of {key, label, type, required?, options?}. Types are text, number, boolean, select and date (YYYY-MM-DD). Only select fields take options (1–50 distinct choices). Keys use lowercase letters, digits and underscores, up to 64 characters, and must be unique throughout the process. There are at most 30 fields per stage and 100 stages. The terminal stage cannot collect fields or have a condition.

Set applies_when to field:needs_review to include a stage only when the needs_review answer is true. This must reference a required boolean from an earlier unconditional stage. The laundry predicate presilla_or_ojal is also supported. Omit the condition to include the stage for every order.

POST /v1/orders/{id}/advance accepts data containing only the current stage’s configured field answers. Required false and zero are valid answers; missing required answers, unknown fields and invalid types are rejected. Answers accumulate in the order’s data and are snapshotted with field labels in each handover’s payload. The assistant uses advance_order.data; MCP uses relay_advance_order.data.

GET /v1/catalogue includes field types, condition syntax and editable templates. Process export/import preserves field definitions. Used stages cannot change type or field schema: add a new stage key instead.

Roles

Relay ships no roles. A role is whatever your company calls the people who do a step — driver, oven, quality control — and writing it on a stage is what creates it; your roles are exactly the roles your stages name. A person is given roles on the Settings page, with set_member_tags, or with dst relay members tag, and may then move the stages that carry them. A stage with no role is open to anyone in the workspace. Owners and admins may act on any stage, and are the only ones who may publish work, recount, close a difference, change prices or edit the process.

Owner, admin and member are the workspace roles Destesi owns; Relay’s roles are yours. See Roles and permissions.

Reports

by-day, by-actor, by-stage, by-workshop, shortfalls-by-client, stage-durations, payroll. Every one reads the hand-over log directly, so nothing can disagree with the board. Add ?format=csv for a download.

Endpoints

Every route below needs a session or a personal access token. Configuration verbs refuse a member as described in Roles.

Method & path	Purpose
GET /v1/auth/me · POST /v1/auth/logout	The signed-in user, with role; end the session
GET /v1/catalogue	Stage types, roles, conditions and reports
`GET	PUT /v1/process`
`GET	POST /v1/orders`
GET /v1/orders/{id}	One order and its whole hand-over log
POST /v1/orders/{id}/claim · /advance · /recount · /note · /define · /photo	Move, correct, annotate or configure an order
`GET	POST /v1/orders/{id}/assignments`
POST /v1/assignments/{id}/finish · DELETE /v1/assignments/{id}	Finish a share; release an unfinished one
`GET	POST /v1/orders/{id}/batches`
`GET	POST /v1/orders/{id}/invoice`
`GET	PUT /v1/settings`
`GET	POST /v1/materials`
GET /v1/inventory/issues · POST /v1/inventory/issues/{id}/retry	Material deductions Inventory has not taken yet
GET /v1/shortfalls · POST /v1/shortfalls/{id}/ack	Counted differences; close one
GET /v1/reports/{name}	A report (?format=csv downloads it)
`GET	POST /v1/clients·/v1/workshops·/v1/rate-cards`
GET /v1/members · PUT /v1/members/{user}/tags	People and their Relay roles
POST /v1/me/telegram/pairing	Link your own Telegram chat for alerts
POST /v1/chat · POST /v1/chat/resume	The assistant, and resuming an approval

Live updates

GET /v1/stream is a server-sent event stream for the workspace board, with event kinds order.published and order.changed. Where live delivery is not configured it answers 503 live_disabled, and the board polls instead.

dst relay

dst relay catalogue                       # the stage types, your roles and the reports
dst relay process show                    # your stages
dst relay process export laundry.json     # seed another workspace from this one
dst relay -w other-shop process import laundry.json

dst relay orders --stage pickup           # one board column
dst relay order create --client <id> --quantity 197
dst relay order claim <order-id>          # "I'm going"
dst relay order advance <order-id> --quantity 197 --presilla
dst relay order advance <order-id> --data '{"request_summary":"Repair","needs_review":false}'
dst relay order show <order-id>           # the whole hand-over log
dst relay order define <order-id> --tasks <rate-card-ids>

dst relay work take <order-id> chafado 300
dst relay work finish <assignment-id>
dst relay batch record <order-id> --operation-key load-1 --machine L3 --doses '[{"material_id":"<mapping-id>","grams":300}]'

dst relay shortfalls                      # what is missing, and on which leg
dst relay invoice <order-id>              # assemble the bill
dst relay report payroll --from 2026-09-01 --to 2026-09-15

process export and process import are the only verbs the terminal has and the assistant does not: moving a process between workspaces is a file operation.