name: kapso-automation
description: Manage Kapso workflows, AI agents, functions, and databases. Edit workflow graphs, configure triggers, manage executions, create functions, and perform database CRUD. Use when building automations, editing workflows, or managing project data.

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
- PROJECT_ID

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