# Workflow

A workflow: the named set of statuses a work item moves through, plus the transitions allowed between them. A project points at one workflow. Statuses and transitions are managed as their own collections: a workflow is created empty.

## Used by
- GET /api/v2/workflows: List workflows (WorkflowList)
- POST /api/v2/workflows: Create a workflow (Workflow)
- GET /api/v2/workflows/{workflow}: Read a workflow (Workflow)
- PATCH /api/v2/workflows/{workflow}: Update a workflow (Workflow)

## Workflow fields
- id (integer, required): Unique identifier.
- name (string ≤ 255, required): Workflow name as shown in the UI, e.g. `Standard`.
- order (integer, required, server-assigned): Display position; set by dragging in plnnrly and not writable. API-created workflows are created at 0 and fall back to the id tiebreaker.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- statuses_count (integer ≥ 0, required): Number of statuses in this workflow.
- links (WorkflowLinks, required)
  - self (url, required): The canonical URI of this record.
  - statuses (url, required): Statuses in this workflow, in workflow order.

## Variants

### WorkflowList

What a collection returns, and what `?view=summary` returns on a single record.

7 fields.
Identical to the detail object above.

### WorkflowSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

2 fields.
Omits: order, created_at, updated_at, statuses_count, links

### WorkflowLinks

The `links` object on this resource.

Keys: self, statuses

## Example
```json
{
  "id": 1,
  "name": "Bug triage",
  "order": 1,
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "statuses_count": 1,
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "statuses": "https://<your-url>/api/v2/work-items/1"
  }
}
```