Get a workspace workflow
Retrieve one catalog workflow with its whole configuration: the chain in states, every transition with its approvers and enabled hooks, and referenced_resources, which resolves each state and approver id that the chain names. Read it before you edit a workflow, so that you send changes against the current chain.
states[].id is the catalog state id. Use referenced_resources.states to show state names, colors, and groups without a second request.
Path parameters
slug:requiredstringThe workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.
pk:requiredstring (uuid)The id of the catalog workflow. A project workflow's id returns 404.
Response shaping
fields:optionalstringComma-separated list of fields to return. Fields you don't request are left out of the response instead of coming back as null, so a missing key means you didn't ask for it and null means the value is null. id is always included, whether or not you name it.
Pass all to get every requestable field. An unknown field name returns 400 with the list of valid names and the closest match, so a typo is caught instead of being silently ignored.
Requestable here: created_at, created_by_id, description, id, is_active, is_default, name, project_ids, projects_count, referenced_resources, states, states_count, updated_at, updated_by_id, work_item_type_ids, work_item_types_count.
See Sparse fields.
Scopes
workspaces.workflows:read
Errors
| Status | Code | Cause |
|---|---|---|
400 | invalid_request | An unknown name in fields. |
401 | unauthorized | Missing or invalid credentials. |
403 | forbidden | Your role or token scope can't view workspace workflows. |
404 | not_found | No such workflow in this workspace's catalog, or it's outside your tenant. |
406 | not_acceptable | The Accept header asks for a representation the API can't produce. |
409 | states_managed_at_project | The workspace doesn't have governance turned on. Use the project's workflows instead. |
429 | rate_limited | Throttled. Honor the Retry-After header before retrying. |
The chain shows enabled hooks only
pre_rules and post_rules list the transition's enabled hooks. For a send_webhook rule, the response masks config.secret as plane_wh_•••• plus its last four characters, and a secret header reports has_value instead of its value. To see every hook, disabled ones included, use List workspace workflow hooks.
curl -X GET \
"https://api.plane.so/api/v2/workspaces/my-team/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/" \
-H "X-Api-Key: $PLANE_API_KEY"import requests
response = requests.get(
"https://api.plane.so/api/v2/workspaces/my-team/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
headers={"X-Api-Key": "your-api-key"},
)
print(response.json())const response = await fetch(
"https://api.plane.so/api/v2/workspaces/my-team/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/",
{
headers: {
"X-Api-Key": "your-api-key",
},
},
);
const data = await response.json();{
"id": "9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88",
"name": "Delivery",
"description": "Engineering delivery flow with a review gate",
"is_active": true,
"is_default": false,
"states_count": 4,
"projects_count": 2,
"work_item_types_count": 1,
"states": [
{
"id": "2c4d16f8-9b3e-4a52-8d71-1f0e6c9a5b48",
"allow_issue_creation": true,
"is_default": true,
"sequence": 10000.0,
"type": "transition",
"transitions": [
{
"id": "8d2f6a41-5c3e-4b97-a1d0-7e9c4b2f8a63",
"transition_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
"rejection_state_id": null,
"member_ids": [],
"required_approvals": null,
"pre_rules": [],
"post_rules": []
}
]
},
{
"id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
"allow_issue_creation": true,
"is_default": false,
"sequence": 20000.0,
"type": "transition",
"transitions": [
{
"id": "d7a3f5c9-0b2e-4d81-b6f4-9e1c3a5d7b20",
"transition_state_id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
"rejection_state_id": null,
"member_ids": [],
"required_approvals": null,
"pre_rules": [
{
"id": "9a1c5e37-8b2d-4f60-a4e9-6c3b7d0f1e28",
"handler_name": "run_script",
"rule_type": "validation",
"config": {
"script_id": "5d8e2a6c-3f1b-4a97-8c04-2e9b7d1f6a35",
"execution_variables": {
"min_estimate": "1"
}
}
}
],
"post_rules": [
{
"id": "e4b7c9a2-3d1f-4e68-8a52-9f0c6b3d7e15",
"handler_name": "send_webhook",
"rule_type": "action",
"config": {
"url": "https://hooks.example.com/plane",
"headers": [
{
"key": "X-Team",
"is_secret": false,
"value": "platform"
}
],
"secret": "plane_wh_••••7c1d"
}
}
]
}
]
},
{
"id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
"allow_issue_creation": false,
"is_default": false,
"sequence": 30000.0,
"type": "approval",
"transitions": [
{
"id": "4b6e1d93-2a7f-4c58-9e30-1d8b5f7a2c46",
"transition_state_id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
"rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
"member_ids": ["a3f92c71-6e4b-4d08-9b5a-1c7e3d9f2b84"],
"required_approvals": 1,
"pre_rules": [],
"post_rules": []
}
]
},
{
"id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
"allow_issue_creation": false,
"is_default": false,
"sequence": 40000.0,
"type": "transition",
"transitions": []
}
],
"referenced_resources": {
"states": {
"2c4d16f8-9b3e-4a52-8d71-1f0e6c9a5b48": {
"id": "2c4d16f8-9b3e-4a52-8d71-1f0e6c9a5b48",
"name": "Backlog",
"color": "#8b8d98",
"group": "backlog",
"sequence": 15000.0,
"default": false,
"project_id": null,
"workspace_id": "b1c4e7a2-5d8f-4a3b-9c6e-0f2d4a7b8c91"
},
"f960d3c2-8524-4a41-b8eb-055ce4be2a7f": {
"id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
"name": "In Progress",
"color": "#3f76ff",
"group": "started",
"sequence": 25000.0,
"default": false,
"project_id": null,
"workspace_id": "b1c4e7a2-5d8f-4a3b-9c6e-0f2d4a7b8c91"
},
"b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53": {
"id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
"name": "In Review",
"color": "#f5a623",
"group": "started",
"sequence": 35000.0,
"default": false,
"project_id": null,
"workspace_id": "b1c4e7a2-5d8f-4a3b-9c6e-0f2d4a7b8c91"
},
"7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613": {
"id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
"name": "Done",
"color": "#26a05f",
"group": "completed",
"sequence": 45000.0,
"default": false,
"project_id": null,
"workspace_id": "b1c4e7a2-5d8f-4a3b-9c6e-0f2d4a7b8c91"
}
},
"users": {
"a3f92c71-6e4b-4d08-9b5a-1c7e3d9f2b84": {
"id": "a3f92c71-6e4b-4d08-9b5a-1c7e3d9f2b84",
"display_name": "priya",
"avatar_url": null,
"is_bot": false,
"first_name": "Priya",
"last_name": "Raman",
"workspace_id": "b1c4e7a2-5d8f-4a3b-9c6e-0f2d4a7b8c91"
}
}
},
"project_ids": ["4af68566-94a4-4eb3-94aa-50dc9427067b", "d1e8a3c5-7f2b-4a96-8e04-3b6c9d1f5a27"],
"work_item_type_ids": ["2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4"],
"created_at": "2026-01-14T09:22:41.478363Z",
"updated_at": "2026-01-15T11:04:52.660219Z",
"created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
"updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}{
"type": "not_found",
"code": "not_found",
"detail": "The requested resource was not found."
}