Work item type workflows overview

In a governed workspace, each project uses one catalog workflow per work item type. These project routes show which workflow applies to each type and where that answer came from. They also let the project change its own pick when the type's governance allows it.

Work item type governance explains the rules that decide the answer, such as the any, constrained, and required modes and workspace pins.

Learn more about workspace governance · Learn more about workflows

The work item type workflow object

Each work item type that is active in the project has one entry. A type counts as active when it is active on the workspace and in the project.

Attributes

• type_id string (uuid)

  The work item type.

• governance string

  Who controls the workflow for this type in this project. One of these values, checked in this order:

  • required: the workspace mandates the workflow.
  • pinned: the workspace pinned the workflow for this project.
  • constrained: the project picks from the type's allowlist.
  • any: the project picks any active catalog workflow.

• allowlist_count integer

  How many workflows are on the type's allowlist. It is 1 under required, where the allowlist holds the mandate, and 0 under any.

• allowlist_total integer

  How many active catalog workflows the workspace has.

• effective_workflow_id string (uuid) or null

  The catalog workflow that applies to the type in this project now. null when neither the pick nor the workspace default workflow has any states.

• effective_workflow_name string or null

  Returned as null. Read the name from options or from the workspace workflows endpoints.

• source string or null

  Where effective_workflow_id came from. One of required, pin, pick, or workspace_default. workspace_default means the project has no pick for the type and the workspace default workflow applies. null when no workflow resolves.

• options array of objects

  The workflows the project may pick, each with workflow_id and name. Under any, it lists every active catalog workflow. Under constrained, it lists the allowlist. It is empty when governance is required or pinned.

Response200

{
  "type_id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
  "governance": "constrained",
  "allowlist_count": 2,
  "allowlist_total": 3,
  "effective_workflow_id": "a1f4c7e2-3b98-4d61-8e25-6c0b9d7f3a14",
  "effective_workflow_name": null,
  "source": "pick",
  "options": [
    {
      "workflow_id": "a1f4c7e2-3b98-4d61-8e25-6c0b9d7f3a14",
      "name": "Standard delivery"
    },
    {
      "workflow_id": "e6b2d9f1-48a7-4c3e-9f50-1d7a8c2b6e93",
      "name": "Regulated release"
    }
  ]
}

Changing a project's pick

Update a work item type workflow sets the workflow a project uses for one type. It's a PATCH. Add ?dry_run=true to count the work items that would move without changing anything.

The workspace can take the decision away from the project in two ways, and each has its own error:

• The type is in required mode. The update returns 403 workflow_mandated.
• The workspace pinned the type's workflow for this project. The update returns 403 workflow_assigned_by_workspace.

Under constrained, a workflow outside the allowlist returns 400 workflow_outside_allowlist. A change that strands work items in states the new workflow doesn't contain needs a state_mapping, or it returns 409 workflow_state_orphans. See The orphan gate.

Governed workspaces only

These routes exist only under governance. In an ungoverned workspace, they return 409 states_managed_at_project because each project owns its workflows. Use Workflows there, where a workflow's work_item_type_ids ties it to types.

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/workflows/	List work item type workflows
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{type_id}/workflow/	Get a work item type workflow
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{type_id}/workflow/	Update a work item type workflow

To preview a re-type or a workflow switch across the whole project, use Preview a workflow fallback.

Changed from v1

• Setting the pick is a PATCH. v1 uses PUT on the same path with the same body. v2 has no PUT anywhere.

See Migrating from v1 for the full list.

Response shaping

These routes don't accept ?fields= or ?expand=. The list returns a plain JSON array, not the paginated data envelope. Errors follow the shared problem+json contract.