Workflows

Create a workflow

Changed on Nov 4, 2026

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.

When the gateway config session_policy_deploy_check is on, a workflow whose fund-moving steps the runner's usable grant does not cover is refused with 409 SESSION_POLICY_NOT_COVERING. required is the grant those steps still need. A fund-moving workflow whose single usable grant has already expired is 409 SESSION_POLICY_EXPIRED, including when the workflow has no end date. A fund-moving step whose target cannot be read stays 409 SESSION_POLICY_TARGET_UNRESOLVED even when that grant has expired. A grant with no recorded expiry is not expired. A grant made for a session signer the gateway no longer uses is 409 SESSION_POLICY_SIGNER_RETIRED: it cannot execute however well it covers the workflow. The owner grants again. A workflow that only notifies passes with no grant. The flag defaults to off, so today's callers are unchanged.

post/workflows

Request

Base URL
https://api.avaprotocol.org/api/v1
Auth
HTTP bearer

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
      }
    }
  ]
}

Changes

Nov 4, 20266b505ebcf3f7 Revision changes
- info
  added the new optional request property ////////
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
Oct 28, 20264ebf07931311 Revision changes
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status

Operation history (12 revisions)

Create a workflow

Request

Request body

Example request

Response 201Created

Example response

Changes

Response