Workflows

Retrieve workflow

Get workflow metadata, status, and execution stats for a specific workflow. This endpoint does not include the expanded canvas definition payload.

Use this endpoint to:

Retrieve workflow metadata before a simple update
Check workflow status and execution count
Inspect timestamps, lock version, and execution activity

Use GET /workflows/{workflow_id}/definition when you need the editor payload with nodes, edges, embedded project data, and WhatsApp configs.

GET

workflows

{workflow_id}

Retrieve workflow

curl --request GET \
  --url https://api.kapso.ai/platform/v1/workflows/{workflow_id} \
  --header 'X-API-Key: <api-key>'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "slug": "inbound-support",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "lock_version": 123,
    "message_debounce_seconds": 123,
    "agent_default_tools_version": 123,
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "execution_count": 1,
    "last_executed_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

workflow_id

string<uuid>

required

Workflow identifier

Response

Workflow details retrieved successfully

Single workflow response

data

object

required

Show child attributes

Update workflowUpdate workflow metadata or replace workflow definition collections. Common updates: - Change workflow name or description - Update workflow definition nodes and edges - Activate workflow by setting status to 'active' - Archive workflow by setting status to 'archived' Definition update semantics: - Omit `definition` to update metadata only. - Omit `definition.nodes` to leave nodes unchanged. - Include `definition.nodes` only when sending the complete desired node set. Nodes omitted from that array are removed. - Omit `definition.edges` to leave edges unchanged. - Include `definition.edges` only when sending the complete desired edge set. Edges omitted from that array are removed. - Use snake_case config keys in API payloads. Successful responses contain workflow metadata, including the new `lock_version`. They do not include the expanded graph. Call `GET /workflows/{workflow_id}/definition` after updating when you need the saved nodes and edges. You can update the definition of an active workflow. Changes take effect immediately for new executions; running executions continue with the snapshot they started with.

Retrieve workflow

curl --request GET \
  --url https://api.kapso.ai/platform/v1/workflows/{workflow_id} \
  --header 'X-API-Key: <api-key>'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "slug": "inbound-support",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "lock_version": 123,
    "message_debounce_seconds": 123,
    "agent_default_tools_version": 123,
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "execution_count": 1,
    "last_executed_at": "2023-11-07T05:31:56Z"
  }
}