Kapso Automation

When to use

Use this skill to build and run Kapso automation: workflow CRUD, graph edits, triggers, executions, function management, and D1 database operations.

Setup

Env vars:

• •KAPSO_API_BASE_URL (host only, no /platform/v1)
• •KAPSO_API_KEY

How to

Edit a workflow graph

1. •Fetch graph: node scripts/get-graph.js <workflow_id> (note the lock_version)
2. •Edit the JSON (see graph rules below)
3. •Validate: node scripts/validate-graph.js --definition-file <path>
4. •Update: node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>
5. •Re-fetch to confirm

For small edits, use edit-graph.js with --old-file and --new-file instead.

If you get a lock_version conflict: re-fetch, re-apply changes, retry with new lock_version.

Manage triggers

1. •List: node scripts/list-triggers.js <workflow_id>
2. •Create: node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>
3. •Toggle: node scripts/update-trigger.js --trigger-id <id> --active true|false
4. •Delete: node scripts/delete-trigger.js --trigger-id <id>

For inbound_message triggers, first run node scripts/list-whatsapp-phone-numbers.js to get phone_number_id.

Debug executions

1. •List: node scripts/list-executions.js <workflow_id>
2. •Inspect: node scripts/get-execution.js <execution-id>
3. •Get value: node scripts/get-context-value.js <execution-id> --variable-path vars.foo
4. •Events: node scripts/list-execution-events.js <execution-id>

Create and deploy a function

1. •Write code with handler signature (see function rules below)
2. •Create: node scripts/create-function.js --name <name> --code-file <path>
3. •Deploy: node scripts/deploy-function.js --function-id <id>
4. •Verify: node scripts/get-function.js --function-id <id>

Set up agent node with app integrations

1. •Find model: node scripts/list-provider-models.js
2. •Find account: node scripts/list-accounts.js --app-slug <slug> (use pipedream_account_id)
3. •Find action: node scripts/search-actions.js --query <word> --app-slug <slug> (action_id = key)
4. •Create integration: node scripts/create-integration.js --action-id <id> --app-slug <slug> --account-id <id> --configured-props <json>
5. •Add tools to agent node via flow_agent_app_integration_tools

Database CRUD

1. •List tables: node scripts/list-tables.js
2. •Query: node scripts/query-rows.js --table <name> --filters <json>
3. •Create/update/delete with row scripts

Graph rules

• •Exactly one start node with id = start
• •Never change existing node IDs
• •Use {node_type}_{timestamp_ms} for new node IDs
• •Non-decide nodes have 0 or 1 outgoing next edge
• •Decide edge labels must match conditions[].label
• •Edge keys are source/target/label (not from/to)

For full schema details, see references/graph-contract.md.

Function rules

async function handler(request, env) {
  // Parse input
  const body = await request.json();
  // Use env.KV and env.DB as needed
  return new Response(JSON.stringify({ result: "ok" }));
}

• •Do NOT use export, export default, or arrow functions
• •Return a Response object

Execution context

Always use this structure:

• •vars - user-defined variables
• •system - system variables
• •context - channel data
• •metadata - request metadata

Scripts

Workflows

Graph

Triggers

Executions

Functions

App integrations

Databases

Notes

• •Prefer file paths over inline JSON (--definition-file, --code-file)
• •action_id is the same as key from search-actions
• •--account-id uses pipedream_account_id from list-accounts
• •Variable CRUD (variables-set.js, variables-delete.js) is blocked - Platform API doesn't support it
• •Raw SQL execution is not supported via Platform API

References

Read before editing:

• •references/graph-contract.md - Graph schema, computed vs editable fields, lock_version
• •references/node-types.md - Node types and config shapes
• •references/workflow-overview.md - Execution flow and states

Other references:

• •references/execution-context.md - Context structure and variable substitution
• •references/triggers.md - Trigger types and setup
• •references/app-integrations.md - App integration and variable_definitions
• •references/functions-reference.md - Function management
• •references/functions-payloads.md - Payload shapes for functions
• •references/databases-reference.md - Database operations

Assets

Related skills

• •whatsapp-messaging - WhatsApp messaging and templates
• •whatsapp-flows - WhatsApp Flows
• •kapso-api - Platform API and customers