Workflow API

Build graphs, then execute them.

Workflows are the core building block of KeeperHub. The SDK gives you a full CRUD interface, execution helpers, enable/disable control, marketplace publication, and graph-building helpers for composing workflows programmatically.

See Executions Read Protocol

workflow graph

trigger -> action -> condition -> branch

graph validation catches:
missing triggers
orphan nodes
dangling edges
self-loops

Workflow methods

The SDK README describes the most common workflow operations. The namespaced module exposes the full set, while the flat API covers the primary tasks.

Method	Purpose	Notes
list(options)	List workflows with optional project, tag, and pagination filters	Use when resolving a workflow by metadata
get(id)	Fetch a single workflow by ID	Returns typed workflow details
create(input)	Create a workflow from a full definition	Accepts nodes, edges, and metadata
update(id, input)	Patch an existing workflow	Use for name, enabled flag, or definition changes
delete(id, options)	Delete a workflow	Optional force flag for active executions
enable(id) / disable(id)	Toggle workflow availability	Often used before execution
execute(id, input)	Start a workflow run	Returns executionId quickly
duplicate(id)	Clone a workflow	Useful for templating and experimentation
download(id)	Fetch the workflow JSON definition	Useful for export and review
goLive(id, options)	Publish a workflow to the marketplace	Links a workflow to public listing flows

Filters

List by project or tag

The list method accepts projectId, tagId, page, and limit so host apps can resolve workflows from a focused slice.

Publication

Duplicate, download, and go live

Use duplication for experiments, download for offline inspection, and goLive when you want to publish a workflow to the marketplace.

Build a workflow graph

The README shows a complete example. This version keeps the same structure while focusing on the pieces a developer needs to understand the graph model.

import {
  KeeperKit,
  createTriggerNode,
  createActionNode,
  createConditionNode,
  createEdge,
  createConditionEdges,
  templateRef,
} from "keeperkit";

const client = new KeeperKit({ apiKey: process.env.KEEPERHUB_API_KEY });

const trigger = createTriggerNode({
  id: "trigger_1",
  label: "Every 5 Minutes",
  triggerType: "schedule",
  config: { interval: "*/5 * * * *" },
});

const action = createActionNode({
  id: "check_balance",
  label: "Check Wallet Balance",
  actionType: "wallet-balance",
  config: { chainId: 11155111, address: "0xYourWalletAddress" },
});

const condition = createConditionNode({
  id: "balance_check",
  label: "Balance Below Threshold",
  expression: `${templateRef("check_balance", "Check Wallet Balance", "result.balance")} < 0.1`,
});

const edges = [
  createEdge({ source: trigger.id, target: action.id }),
  createEdge({ source: action.id, target: condition.id }),
  ...createConditionEdges(condition.id, "notify_discord", "no_action"),
];

const workflow = await client.createWorkflow({
  name: "Sepolia Balance Monitor",
  description: "Alerts when wallet balance drops below 0.1 ETH",
  nodes: [trigger, action, condition],
  edges,
  enabled: true,
});

Validation

Check graphs locally

Validate the workflow graph before sending it to KeeperHub so missing triggers, orphan nodes, or dangling edges are caught earlier.

Helpers

Template references

Use templateRef, parseTemplateRef, and extractTemplateRefs to reference previous node outputs in conditions and actions.

import { validateWorkflowGraph, validateNodeConfig } from "keeperkit";

const result = validateWorkflowGraph(nodes, edges);
if (!result.valid) {
  for (const error of result.errors) {
    console.error(error.message);
  }
}

const nodeResult = validateNodeConfig(actionNode, ["chainId", "address"]);