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. Unrequested keys are omitted from the response, not returned as null, so absent means "not requested" and null means "actually null". id always comes back whether or not you name it.
Pass all for every requestable field. An unknown name is a 400 that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.
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. |
402 | payment_required | The OpenAPI schema declares 402 for every catalog route. This endpoint checks no plan feature, so it never returns 402. |
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."
}