v11

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-023710598.2 KB

Workflows

Create a workflow

Persist a new workflow definition. Each chain-aware trigger and node carries its own required chainId (there is no workflow-level chain); the server validates those chains and ensures the smart wallet belongs to the authenticated user. Returns the persisted Workflow with its server-assigned id and createdAt.

post/workflows

Request body

namestring

smartWalletAddressstring required

Lowercase or checksummed hex EOA / contract address.

inputVariablesInputVariables

Free-form key-value bag of values used to resolve {{variable.path}} template references inside trigger and node configs. Conventional well-known keys: settings.runner (smart wallet address), settings.chainId (chain id). camelCase keys; back-compat support for snake_case keys exists during the migration window.

startAtinteger

expiredAtinteger

maxExecutioninteger

Optional cap on total executions. Omit the field to take the server default. Sending 0 (or a negative) is rejected rather than treated as unlimited: unlimited execution is not offered, because every run spends metered provider quota.

Example request

{
  "smartWalletAddress": "0x82F2Dd9a552a69f2ceD7Ff2D05c43aB8430158FB",
  "trigger": {
    "config": {
      "chainId": 11155111
    }
  },
  "nodes": [
    {
      "config": {
        "destination": "0x82F2Dd9a552a69f2ceD7Ff2D05c43aB8430158FB",
        "chainId": 11155111
      }
    }
  ]
}

Response

Workflow created.

idstring required

ULID identifier (26-char Crockford base32).

namestring

ownerstring required

Lowercase or checksummed hex EOA / contract address.

smartWalletAddressstring required

Lowercase or checksummed hex EOA / contract address.

inputVariablesInputVariables

status'enabled' | 'disabled' | 'running' | 'completed' | 'failed' required

Lifecycle status. enabled means actively monitored; disabled is paused. running, completed, failed are terminal-ish states emitted during/after execution.

startAtinteger

Unix-epoch milliseconds — workflow is inert before this time.

expiredAtinteger

Unix-epoch milliseconds — workflow is inert after this time.

maxExecutioninteger

Cap on how many times this workflow may execute. The workflow reaches status completed once executionCount hits this value. Present and finite on every workflow created since the server began assigning a default — a create request that omits the field takes that default, and one that sends 0 or a negative is rejected, so "run forever" is not expressible. Absent on workflows created before that change and stored uncapped; those keep running without a limit, and remainingExecutions is likewise absent for them.

executionCountinteger

How many times this workflow has executed so far.

remainingExecutionsinteger

Runs left before the workflow completes — maxExecution minus executionCount, floored at 0. Derived server-side so clients do not have to reproduce the arithmetic (and so an absent executionCount on a never-run workflow cannot be misread). Reported as 0 rather than omitted once the budget is spent. Absent only on legacy uncapped workflows, where no finite number exists.

completionReason'TASK_COMPLETION_REASON_UNSPECIFIED' | 'TASK_COMPLETION_REASON_MAX_EXECUTIONS_REACHED' | 'TASK_COMPLETION_REASON_EXPIRED'

Why the workflow reached a terminal state. An exhausted execution budget and a passed expiry both produce status completed, so the status alone cannot distinguish them. Absent or UNSPECIFIED while the workflow is still runnable, and on workflows that terminated before this field existed. Cancellation is not represented — cancelling deletes the workflow rather than leaving a record.

createdAtinteger

Unix-epoch milliseconds — when the workflow was first created.

completedAtinteger

Unix-epoch milliseconds — when the workflow reached a terminal state.

Example response

{
  "id": "01JG2FE5MDVKBPHEG0PEYSDKAC",
  "owner": "0x82F2Dd9a552a69f2ceD7Ff2D05c43aB8430158FB",
  "smartWalletAddress": "0x82F2Dd9a552a69f2ceD7Ff2D05c43aB8430158FB",
  "trigger": {
    "config": {
      "chainId": 11155111
    }
  },
  "nodes": [
    {
      "config": {
        "destination": "0x82F2Dd9a552a69f2ceD7Ff2D05c43aB8430158FB",
        "chainId": 11155111
      }
    }
  ]
}