List workflow states for a domain

GET

/workflow/states

• Local development behind nginx (port 8088 by default)

Returns every state in the requested domain (post, asset, …) ordered by sort_order. Used by the upload modal’s “set initial state” dropdown and any management surface that needs to render state pickers. The set of domains and states is seeded at install time; this endpoint is read-only.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Query Parameters

domain

required

string

>= 1 characters <= 64 characters

Example

post

Domain key as stored in workflow_states.domain. Common values: post (all posts), asset:1 (assets of resource type 1 — Photo), asset:3 (Video), etc.

Responses

200

States in the requested domain

Array<object>

One node in a workflow state machine. States are scoped to a domain (post, asset). Initial / terminal flags are read-only — the underlying workflow_state table is seeded, not edited from the API.

object

id

required

string format: uuid

domain

required

Domain key (e.g. post, asset:1)

string

code

required

Stable machine identifier (e.g. draft)

string

label

required

Human label (e.g. Draft)

string

sort_order

required

integer format: int32

is_initial

required

boolean

is_terminal

required

boolean

icon

required

Short token (e.g. “check”, “clock”, “x-circle”) the frontend maps to an SVG in its iconset. Empty string = no icon override (frontend picks a default).

string

color

required

Hex color (e.g. #16a34a) for the state badge background. Empty string = frontend falls back to a neutral tone.

string

requires_note

required

When true, workflow.Service.Transition rejects calls that move INTO this state with an empty note. Useful for rejection / needs-work states where the reason matters for audit and the originating user.

boolean

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}