Skip to content

List the workflow states of a domain

GET
/workflow/states

Returns every workflow state defined for one domain, in display order, so a client can label or filter by state.

You need to be signed in, but no particular permission: any signed-in account can read any domain’s states. Signed-out callers get 401, whether or not the install is public.

domain is matched exactly, without trimming or changing case. post is the domain of posts, and asset: followed by an asset type’s number, such as asset:1, is the domain of that asset type. Out of the box only post and asset:1 have states, and states added for another domain directly in the database are returned the same way. A value with no states, such as a misspelled or wrong-case domain, returns an empty list rather than an error, and the declared length limits aren’t checked. A missing or repeated domain gets a plain-text 400, even when you aren’t signed in. An empty domain gets 401 when you aren’t signed in, and otherwise a 400 with the reason in error.

States are sorted by sort_order, then by code. The list includes starting and final states and isn’t paged. It is the domain’s vocabulary only: it doesn’t say which moves between states are allowed, who may make them, or which state a given post or asset is in. No endpoint creates or changes states.

Each server process remembers a domain’s list once it has read it, with no expiry, and editing the states themselves doesn’t tell it to read the list again. A list, including an empty one, can therefore stay out of date indefinitely after states are added or edited directly in the database. A process drops a remembered list only when it restarts, when it needs room for other domains, or when it receives a request to clear its cached data, and then reads the list again on the next request. None of these is certain to happen, and even after one, the next answer may still be out of date. Server errors get a plain-text 500.

domain
required
string
>= 1 characters <= 64 characters
Example
post

The domain to list: post, or asset: and an asset type’s number, such as asset:1. Matched exactly; a value that names no domain returns an empty list.

The domain’s states, sorted by sort_order and then code; empty when the domain has none.

Array<object>

One workflow state of a domain. States are set up in the database; no endpoint creates or changes them.

object
id
required
string format: uuid
domain
required

The domain the state belongs to, such as post or asset:1.

string
code
required

The state’s identifier within its domain, such as published. Two domains can each have a state with the same code, and they are different states, so use the domain and code together.

string
label
required

The display name, such as Published.

string
sort_order
required

The state’s position in the list; lower values come first. Values can be negative, and states with the same value are ordered by code.

integer format: int32
is_initial
required

Whether this is the domain’s starting state. A domain has at most one, and may have none.

boolean
is_terminal
required

Whether the state is marked as final. The server only reports it; it doesn’t stop moves out of the state.

boolean
icon
required

A short icon name, such as check-circle, for the client to map to an icon; empty when the state has none.

string
color
required

A color for the state’s badge, such as #16a34a; empty when the state has none. The format isn’t checked.

string
requires_note
required

Whether a move into this state must include a note. Post moves are checked, scheduled ones included: a move with an empty note, or only spaces, is refused. A scheduled change to an asset’s state isn’t checked. No state requires a note out of the box.

boolean

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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"
}