--- title: "Retrieve workflow definition" method: GET path: "/workflows/{workflow_id}/definition" tags: ["Workflows"] --- # Retrieve workflow definition `GET /workflows/{workflow_id}/definition` Get the editor-oriented workflow payload for a specific workflow. This endpoint returns everything needed to load the canvas: - Base workflow metadata - `definition.nodes` built from `flow_steps` - `definition.edges` built from `flow_edges` Response details: - `definition.nodes[].id` is the workflow step identifier, not the database ID - `definition.edges[].id` is the persisted edge UUID - `definition.nodes[].data.node_type` is the canonical backend node type - `definition.nodes[].data.config` changes shape by node type - Config fields are returned in snake_case - Function and call-workflow references are returned as IDs in the Platform API; the Kapso CLI can export them as slugs for local source repos Use this endpoint when building or syncing a visual workflow editor, exporting a workflow graph, or cloning an existing workflow definition. ## Response `200` Workflow definition retrieved successfully - WorkflowWithDefinitionResponse — Single workflow response including the canvas definition and editor metadata - `data` WorkflowWithDefinition, required — Expanded workflow payload returned by `GET /workflows/{workflow_id}/definition`. This is the editor-oriented response: it contains the workflow metadata plus the full canvas graph. - `id` string, uuid, required — Unique workflow identifier - `name` string, required — Workflow name (unique per project) - `slug` string, required — URL-safe workflow identifier (lowercase alphanumeric with hyphens). Stable across renames — useful as an external sync key. Auto-generated from `name` on create if not provided. Unique within the project. - `description` string, nullable — Optional workflow description - `status` 'draft' | 'active' | 'archived', required — Workflow lifecycle status: - `draft`: Under development, not executable - `active`: Published and executable - `archived`: Inactive, no longer in use - `lock_version` integer, nullable — Optimistic locking version. Increment on each update to prevent concurrent modification conflicts. Include this value when updating to ensure you're working with the latest version. - `message_debounce_seconds` integer, nullable — Debounce window for incoming messages in seconds (default: 1). When a user sends multiple messages rapidly, the workflow waits this duration before processing to batch messages together. Prevents workflow from reacting to every keystroke. - `agent_default_tools_version` integer, nullable — Version used to decide which built-in agent tools are required by default for this workflow. - `inbound_message_read_mode` 'disabled' | 'read_only' | 'read_with_typing' — Controls how inbound WhatsApp messages are marked as read before the workflow responds (default: read_with_typing). - `disabled`: Do nothing — messages are not marked as read - `read_only`: Mark messages as read without showing a typing indicator - `read_with_typing`: Mark as read and show a typing indicator before responding - `created_at` string, date-time, required — Workflow creation timestamp - `updated_at` string, date-time, required — Last modification timestamp - `project_id` string, uuid — Project this workflow belongs to - `execution_count` integer — Total number of times this workflow has been executed - `last_executed_at` string, date-time, nullable — Timestamp of most recent execution, null if never executed - `definition` WorkflowDefinition, required — Full workflow graph definition used by the canvas editor. - `nodes` WorkflowDefinitionNode[], required — Canvas nodes derived from `flow_steps`. `id` is the step identifier used inside the workflow definition, not the database primary key. - `id` string, required — Stable step identifier within the workflow graph. This matches `flow_steps.identifier` and is what edges reference via `source` and `target`. - `type` string, required — Canvas renderer type. The API currently returns `flow-node`. - `position` WorkflowDefinitionNodePosition, required — Canvas position of the node. - `x` number, required — Horizontal canvas position. - `y` number, required — Vertical canvas position. - `data` WorkflowDefinitionNodeData, required — Node payload rendered under `definition.nodes[].data`. - `node_type` string, required — Persisted workflow node type. Common values returned by the Rails serializer: - `start` - action node types from executable actions such as `send_text`, `send_template`, `send_interactive`, `webhook`, `set_variable`, `handoff` - `wait_for_response` - `decide` - `agent` - `call` - `config` union, required — Node configuration payload. Shape depends on `node_type`. Built-in shapes returned by the definition endpoint: - `start`: empty object - `wait_for_response`: timeout and variable capture settings - `decide`: decision strategy, branches, and model/function settings - `agent`: model settings plus nested tools, webhooks, knowledge bases, and MCP servers - `call`: referenced workflow ID/name and error variable mapping Action nodes use the underlying action model's `to_config` output, so keys vary by action type. - WorkflowNodeStartConfig — Empty config for the `start` node. - WorkflowNodeSendTextConfig — Config for `send_text` nodes. - … - WorkflowNodeSendTemplateConfig — Config for `send_template` nodes. - … - WorkflowNodeSendInteractiveConfig — Config for `send_interactive` nodes. - … - WorkflowNodeWaitForResponseConfig — Config returned for `wait_for_response` nodes. - … - WorkflowNodeDecideConfig — Config returned for `decide` nodes. - … - WorkflowNodeFunctionConfig — Config for `function` nodes. - … - WorkflowNodeWebhookConfig — Config for `webhook` nodes. - … - WorkflowNodeAgentConfig — Config returned for `agent` nodes. - … - WorkflowNodeCallConfig — Config returned for `call` nodes. - … - WorkflowNodeHandoffConfig — Config for `handoff` nodes. - … - WorkflowNodeSetVariableConfig — Config for `set_variable` nodes. - … - WorkflowNodeEmitEventConfig — Config for `emit_event` nodes. - … - object - `display_name` string, required — Human-friendly label shown in the visual editor. - `edges` WorkflowDefinitionEdge[], required — Canvas edges derived from `flow_edges`. - `id` string, uuid, required — Edge identifier (`flow_edges.id`). - `source` string, required — Source node identifier (`flow_steps.identifier`). - `target` string, required — Target node identifier (`flow_steps.identifier`). - `label` string, nullable — Transition label, usually `next` or a decision branch label. - `type` string, required — Canvas edge renderer type. The API currently returns `default`. - `flow_condition_id` string, uuid, nullable — Condition ID attached to decide-step edges. Null for non-decision edges. ## Other responses - `401` — Missing or invalid API key - `404` — Resource not found --- [API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)