Workflows

Update workflow

Update 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.

PATCH

workflows

{workflow_id}

Update workflow

curl --request PATCH \
  --url https://api.kapso.ai/platform/v1/workflows/{workflow_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow": {
    "name": "<string>",
    "slug": "inbound-support",
    "description": "<string>",
    "message_debounce_seconds": 123,
    "lock_version": 123,
    "definition": {
      "nodes": [
        {
          "id": "send_intro",
          "position": {
            "x": 360,
            "y": 120
          },
          "data": {
            "config": {},
            "display_name": "<string>"
          },
          "type": "flow-node"
        }
      ],
      "edges": [
        {
          "source": "start",
          "target": "send_intro",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "label": "next",
          "type": "default",
          "flow_condition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ]
    }
  }
}
'

{
  "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

Body

application/json

workflow

object

required

Show child attributes

Response

Workflow updated successfully

Single workflow response

data

object

required

Show child attributes

Retrieve workflow definitionGet 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.

Update workflow

curl --request PATCH \
  --url https://api.kapso.ai/platform/v1/workflows/{workflow_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow": {
    "name": "<string>",
    "slug": "inbound-support",
    "description": "<string>",
    "message_debounce_seconds": 123,
    "lock_version": 123,
    "definition": {
      "nodes": [
        {
          "id": "send_intro",
          "position": {
            "x": 360,
            "y": 120
          },
          "data": {
            "config": {},
            "display_name": "<string>"
          },
          "type": "flow-node"
        }
      ],
      "edges": [
        {
          "source": "start",
          "target": "send_intro",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "label": "next",
          "type": "default",
          "flow_condition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ]
    }
  }
}
'

{
  "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"
  }
}