Skip to Content
APIWorkflows

Workflows API

Manage workflows programmatically.

List Workflows

GET /api/workflows

Returns all workflows for the authenticated user (session) or organization (API key).

Query Parameters

ParameterTypeDescription
projectIdstringOptional. Filter workflows by project ID
tagIdstringOptional. Filter workflows by tag ID

Example

GET /api/workflows?projectId=proj_123&tagId=tag_456

Response

[
  {
    "id": "wf_123",
    "name": "My Workflow",
    "description": "Monitors ETH balance",
    "visibility": "private",
    "nodes": [],
    "edges": [],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Get Workflow

GET /api/workflows/{workflowId}

Returns a single workflow by ID.

Response

{
  "id": "wf_123",
  "name": "My Workflow",
  "description": "Monitors ETH balance",
  "visibility": "private",
  "nodes": [...],
  "edges": [...],
  "publicTags": [
    {
      "id": "tag_1",
      "name": "DeFi",
      "slug": "defi"
    }
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "isOwner": true
}

Public workflows include a publicTags array showing all assigned tags.

Create Workflow

POST /api/workflows/create

Request Body

{
  "name": "New Workflow",
  "description": "Optional description",
  "projectId": "proj_123",
  "nodes": [
    {
      "id": "trigger",
      "type": "trigger",
      "data": {
        "label": "Schedule Trigger",
        "config": { "triggerType": "Schedule", "scheduleCron": "*/30 * * * *" }
      }
    },
    {
      "id": "supply-aave",
      "type": "action",
      "data": {
        "label": "Supply USDC to Aave",
        "config": {
          "actionType": "aave-v3/supply",
          "network": "8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "amount": "100000000",
          "onBehalfOf": "0x0000000000000000000000000000000000000000"
        }
      }
    }
  ],
  "edges": [
    {
      "id": "trigger->supply-aave",
      "source": "trigger",
      "target": "supply-aave"
    }
  ]
}

Note on Node Format: For action nodes, set the outer type to "action" and place the plugin slug in config.actionType. The data object contains label and config; status and position are optional and auto-assigned by the API if omitted. Trigger nodes use outer type: "trigger" with config.triggerType set to the Pascal-case trigger name.

The server normalizes the request before persisting it, so the saved node will also include an inner data.type field set to the kind discriminator ("trigger" or "action"). You do not need to send data.type yourself; if you do, it must match the outer type. As a convenience, sending the plugin slug at the outer type (for example "type": "aave-v3/supply") is also accepted, and the server rewrites it into config.actionType during normalization.

name, nodes, and edges are required. description, projectId, tagId, and enabled are optional. projectId assigns the workflow to a project; tagId assigns it to an organization tag for categorization; enabled (boolean) controls whether the workflow is active on creation.

Response

Returns the created workflow with a default trigger node and an empty action node connected to it.

Update Workflow

PATCH /api/workflows/{workflowId}

Request Body

{
  "name": "Updated Name",
  "description": "Updated description",
  "projectId": "proj_123",
  "tagId": "tag_456",
  "nodes": [...],
  "edges": [...],
  "visibility": "private"
}

The tagId field assigns the workflow to an organization tag for categorization.

Delete Workflow

DELETE /api/workflows/{workflowId}

Returns 409 Conflict if the workflow has execution history. Use the force query parameter to cascade delete all runs and logs:

DELETE /api/workflows/{workflowId}?force=true

Execute Workflow

POST /api/workflows/{workflowId}/execute

Manually trigger a workflow execution. The singular form POST /api/workflow/{workflowId}/execute is also accepted for backward compatibility.

Request Body

{
  "input": { "key": "value" }
}

The input field is optional. It maps to the workflow’s trigger input and is passed to the first node of the run.

Example

curl -X POST https://app.keeperhub.com/api/workflows/wf_123/execute \
  -H "Authorization: Bearer $KEEPERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {}}'

Response

{
  "executionId": "exec_123",
  "status": "running"
}

Webhook Trigger

POST /api/workflows/{workflowId}/webhook

Trigger a workflow via webhook. Requires API key authentication.

Duplicate Workflow

POST /api/workflows/{workflowId}/duplicate

Creates a copy of an existing workflow.

Download Workflow

GET /api/workflows/{workflowId}/download

Download workflow definition as JSON.

Generate Code

GET /api/workflows/{workflowId}/code

Generate SDK code for the workflow.

Claim Workflow

POST /api/workflows/{workflowId}/claim

Claim an anonymous workflow into the authenticated user’s organization. Only the original creator of the anonymous workflow can claim it.

Publish Workflow (Go Live)

PUT /api/workflows/{workflowId}/go-live

Publish a workflow to make it publicly visible with metadata and tags.

Request Body

{
  "name": "Public Workflow Name",
  "publicTagIds": ["tag_1", "tag_2"]
}

The name is required. publicTagIds is an array of public tag IDs to associate with the workflow (maximum 5 tags).

List Public Workflows

GET /api/workflows/public

Returns all public workflows with optional filtering.

Query Parameters

ParameterTypeDescription
featuredbooleanOptional. Filter for featured workflows (?featured=true)
featuredProtocolstringOptional. Filter for protocol-featured workflows (e.g., ?featuredProtocol=sky)
tagstringOptional. Filter by public tag slug (e.g., “defi”, “nft”)

Response

[
  {
    "id": "wf_123",
    "name": "Public Workflow",
    "description": "Description",
    "nodes": [...],
    "edges": [...],
    "publicTags": [
      {
        "id": "tag_1",
        "name": "DeFi",
        "slug": "defi"
      }
    ],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Workflow Taxonomy

GET /api/workflows/taxonomy

Returns distinct categories and protocols from all public workflows. Useful for building filter UIs.

Response

{
  "categories": ["defi", "nft"],
  "protocols": ["uniswap", "aave-v3"]
}
POST /api/hub/featured

Mark a workflow as featured in the hub. Requires internal service authentication (hub service). Accepts optional category, protocol, and featuredOrder fields alongside the workflowId.

List Action Schemas

GET /api/mcp/schemas

Returns the complete registry of available workflow actions, triggers, and templates. Essential for programmatic workflow generation to discover valid action configurations.

Response Structure

{
  "version": "1.0.0",
  "actions": {
    "web3/check-balance": {
      "actionType": "web3/check-balance",
      "label": "Check Balance",
      "category": "web3",
      "integration": "web3",
      "requiredFields": { "network": "string (chain ID)", "address": "string" },
      "optionalFields": {},
      "outputFields": { "balance": "..." },
      "requiresCredentials": false
    },
    "Condition": {
      "actionType": "Condition",
      "label": "Condition",
      "category": "System",
      "requiredFields": { "condition": "string (JS expression)" },
      "optionalFields": { "conditionConfig": "object (visual builder state)" },
      "sourceHandles": ["true", "false"]
    }
  },
  "triggers": {
    "Schedule": {
      "triggerType": "Schedule",
      "label": "Schedule",
      "requiredFields": { "scheduleCron": "string" },
      "optionalFields": { "scheduleTimezone": "string" }
    },
    "Manual": { "triggerType": "Manual", "label": "Manual", "requiredFields": {} }
  },
  "chains": [...],
  "platform": { "wallet": {...}, "proxyContracts": {...}, "abiHandling": {...} },
  "templateSyntax": { "pattern": "{{@nodeId:Label.field}}" },
  "builtinVariables": {
    "nodeId": "__system",
    "nodeLabel": "System",
    "variables": { "unixTimestamp": {...}, "unixTimestampMs": {...}, "isoTimestamp": {...} }
  },
  "workflowStructure": { "nodeStructure": {...}, "edgeStructure": {...} },
  "tips": ["actionType must match exactly", "..."]
}

Note on Action Types: The keys in the actions object are the values to use in config.actionType when creating workflow nodes.

  • Plugin actions use a {pluginType}/{slug} format (e.g., "web3/check-balance", "aave-v3/supply").
  • System actions use Pascal-case with spaces between words (e.g., "Condition", "For Each", "HTTP Request"). System actions do not have a requiresCredentials field.
  • Triggers are listed under the triggers key (not actions) and their values map to config.triggerType on trigger nodes.
  • The endpoint self-documents the correct node and edge shapes under the workflowStructure and edgeStructure keys — use these as the source of truth for programmatic workflow generation.
AuthenticationExecutions