API: Workflow endpoints

The API workflow endpoints let a client read a record's current state and execute one of the transitions defined by its Resource. The workflow definition remains the source of truth: the client sends a transition name, and SeviaFlow checks whether that transition can run for the record.

1. Enable workflow access

Two settings must be enabled: the Resource must expose its API, and its API definition must enable workflow access with flow().

public static function api(ApiResource $api): ApiResource
{
    return $api
        ->enabled()
        ->readable(['id', 'order_number', 'status'])
        ->flow();
}

Installing the API adapter alone does not expose every Resource or its workflow. The configured API middleware and Resource authorization still apply. See Authorization for the access-control responsibilities.

2. Read the current state and available transitions

Send a GET request for the record's /flow endpoint:

GET /api/admin/resources/orders/42/flow

The response contains the current state and transitions matching the record's current state and transition conditions:

{
  "data": {
    "state": {
      "name": "pending_payment",
      "label": "Pending payment",
      "color": "yellow",
      "final": false
    },
    "available_transitions": [
      {
        "name": "mark_paid",
        "label": "Mark as paid",
        "danger": false,
        "requires_confirmation": true,
        "requires_comment": false
      },
      {
        "name": "cancel",
        "label": "Cancel order",
        "danger": true,
        "requires_confirmation": true,
        "requires_comment": true
      }
    ]
  }
}

Response value	Meaning
`state.name`	The resolved state name. It normally comes from the model's configured state field; if that field is empty, SeviaFlow uses `initialState()`.
`state.label`	The human-readable label configured for that state, or a label derived from its name.
`state.color`	The optional color token configured for the state. It is presentation metadata; see Workflows.
`state.final`	Whether the state was marked with `final()`. This flag does not by itself block transitions.
`available_transitions`	Transitions allowed from the current state that pass `visibleIf`, transition authorization, and `canRunIf`. Each item includes its name, label, danger flag, and confirmation/comment requirements.

The endpoint checks that the caller can view the record. A transition appearing in this response does not replace the update-authorization check performed when it is executed.

3. Execute a transition

Send a POST request to the endpoint containing the transition's name. Use the machine name from the workflow definition, not its display label.

POST /api/admin/resources/orders/42/flow/mark_paid
Content-Type: application/json

{
  "confirmed": true,
  "comment": "Payment received and verified."
}

Include confirmed: true when requiresConfirmation() is enabled; otherwise it defaults to false. Include a non-empty comment when requiresComment() is enabled. The comment is saved with the workflow activity.

A successful request returns the record ID, its updated state, and a message. The message comes from successMessage() or the default success text.

{
  "data": {
    "id": 42,
    "state": {
      "name": "paid",
      "label": "Paid",
      "color": "green"
    }
  },
  "message": "Order marked as paid."
}

4. Understand validation and authorization

403 Forbidden: the caller is not authorized to view the record or update it with a transition.
404 Not Found: the record is missing, the Resource API or flow endpoint is disabled, or the Resource workflow has no states or no transitions.
422 Unprocessable Entity: the transition is unknown or does not allow the current state, a required confirmation or comment is missing, or a workflow condition blocks execution.
409 Conflict: the record's state changed while the transition was being processed; read the flow again and decide whether to retry.

Execution checks the Resource's update authorization, the transition's authorize and canRunIf rules, and any required confirmation or comment. A handler failure rolls back the database state change and workflow activity. errorMessage() supplies the fallback response message for an unexpected handler failure; validation errors use their own messages.

When a workflow is configured, change its state through a transition endpoint instead of assigning a new state in an ordinary API update. The API adapter rejects direct changes to the workflow state field.

For the state and transition configuration, callback examples, and color conventions, see Workflows.