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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Example
postThe 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.
Responses
Section titled “ Responses ”The domain’s states, sorted by sort_order and then code; empty when the domain has none.
One workflow state of a domain. States are set up in the database; no endpoint creates or changes them.
object
The domain the state belongs to, such as post or asset:1.
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.
The display name, such as Published.
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.
Whether this is the domain’s starting state. A domain has at most one, and may have none.
Whether the state is marked as final. The server only reports it; it doesn’t stop moves out of the state.
A short icon name, such as check-circle, for the client to map to
an icon; empty when the state has none.
A color for the state’s badge, such as #16a34a; empty when the
state has none. The format isn’t checked.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}