> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Block reference

> Inputs, outputs, behavior, and limits for every automation block

Every step has an `id`, a unique `key` within its section, a display `name`, an `action`, optional `input` mappings, an optional `when` condition, and `onError` (`stop` or `continue`). Use `steps:<key>` to reference earlier outputs. A step key starts with a letter and contains only letters, digits, and underscores, up to 40 characters.

Examples below are **individual step fragments**, not complete definitions. Place them in a section's `steps` array. Replace resource identifiers with resources in your workspace.

## Integrations

### Connector — `connector`

Execute a resource from a configured connector, such as looking up a customer or creating a ticket. Choose `connector` and `resource`; map resource inputs with the names required by its schema, including dotted paths such as `body.customerId` or `path.id`.

```json theme={null}
{
  "id": "lookup_step",
  "key": "lookup",
  "name": "Look up a record",
  "action": { "type": "connector", "connector": "customer-system", "resource": "get-customer" },
  "input": { "path.id": "body:customerId" },
  "onError": "stop"
}
```

The output is the connector's data payload when a `data` field is present, otherwise its result. The current executor resolves connector configuration in **production**; a separate test automation does not implicitly select a staging connector. Test mode simulates connector calls, including reads.

### HTTP — `http`

Call an HTTPS API with `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Configure `url`, optional `query`, `headers`, `body`, and `credentialId`.

* `GET` input mappings become query parameters, merged with `action.query`.
* For other methods, an explicit `action.body` wins; otherwise mapped inputs become the request body.
* Output is the response body. HTTP errors fail the step.
* Use a credential for authentication. Sensitive headers such as `Authorization`, `Cookie`, and `X-API-Key` cannot be embedded in the action.
* With a credential, the URL's server must be fixed, not supplied by an event variable. Private/internal network destinations are restricted in hosted production.

```json theme={null}
{
  "id": "notify_step",
  "key": "notify",
  "name": "Notify an external system",
  "action": {
    "type": "http",
    "method": "POST",
    "url": "https://api.example.com/events",
    "body": { "recordId": "{{body:id}}", "state": "processed" }
  },
  "onError": "stop"
}
```

## Data and state

### Read data — `kv.get`

Read a workspace KV value using `namespace` and `key`. The namespace is a fixed identifier; the key can contain variables. Returns the stored value or `null` when absent. Use an If block to distinguish a missing record from a present one.

### Write data — `kv.set`

Store `input.value`, or the mapped input object when `value` is absent. Choose either `ttlSeconds` (duration) or `expiresAt` (absolute ISO timestamp with timezone), never both. `expiresAt` can reference a prior step; a past date skips the write and an invalid date fails it. Without either field, no expiration is requested by this block.

```json theme={null}
{
  "id": "context_step",
  "key": "context",
  "name": "Keep message context",
  "action": {
    "type": "kv.set",
    "namespace": "message-context",
    "key": "{{steps:send.providerMessageId}}",
    "ttlSeconds": 86400
  },
  "input": { "value": "steps:prepare" },
  "onError": "stop"
}
```

Successful writes return `namespace` and `key`; an expired absolute deadline returns a skipped result. KV does not automatically select an environment: use separate namespaces or keys where needed.

### Read / write agent memory — `memory.get`, `memory.set`

Read or append a structured record compatible with an agent's memory contract. Set `agentId`, `environment` (`staging` or `production`), `key`, and `prefix`.

| Format | Stored record | Use |
| - | - | - |
| `keyed` (default) | Prefix followed by JSON with `k` and `v` | A named record under the selected memory key |
| `json` | Prefix followed by the JSON value directly | Existing agent records that store raw JSON |

Only `json` permits an empty prefix and a `namespace:key` form for the key. Do not add an agent or staging prefix yourself; the memory block scopes the record to the selected agent and environment. A read returns the latest compatible value, or `null`. A write takes `input.value` (or the mapped input object) and returns the key.

Writing memory **does not merge objects automatically**. To add a pending interaction without deleting registration fields: read the record, transform `{ ...existing, pending: newContext }`, then write it. Coordinate concurrent updates; this read/modify/write pattern is not an atomic transaction with another run or the agent. Memory is not the same as KV and is not a conversation-message send.

### Read configuration — `config.select`

Select a non-secret configuration value from a named credential. Supply `credentialName`, `allowedValues` (1–32 distinct strings), and a `defaultValue` in that list. The output is `{ "value": "selected-option" }`. Missing or unlisted values use the default; infrastructure failures can be retried.

Use this for bounded settings such as a mode or region. It is **not** a general secret reader, a whitelist-membership operation, or a way to expose arbitrary credential contents to transforms.

### Transform — `transform`

Run a synchronous JavaScript function in a restricted execution environment:

```javascript theme={null}
function transform(input) {
  const customer = input.steps.lookup;
  return {
    id: input.body.id,
    eligible: customer?.enabled === true,
    label: `Record ${input.body.id}`
  };
}
```

The function receives `body`, `query`, `headers`, `event`, `steps`, and mapped `input`. Return JSON-compatible data. Helpers include `sha256`, `formatMoney`, and `formatDate`. Transform is for normalization, validation, mapping, and calculations; it has no Node.js imports, filesystem, network, or credential access. Use integration blocks for I/O.

Code is limited to 20 KB. Runtime defaults include a 500 ms execution budget and 256 KB output limit. Throw an error to reject invalid data; do not use an LLM for exact identifier validation or authorization.

## Messaging, AI, and agents

### Send message — `message.send`

Send WhatsApp messages through a configured connection. Supply `channel: "whatsapp"`, `connectionId` when needed, and mapped `to`. An optional `reference` associates later status events with your business identifier; it does not replace a deduplication policy.

| Format | Configuration / mapped input |
| - | - |
| `template` (default) | `template`, optional `language` (default `pt_BR`), `input.vars` for body parameters |
| `buttons` | `input.text` and `input.buttons`, an array of `{id, title}` |

The template block builds **body text parameters** from `vars` (array or ordered values); it is not an arbitrary template-components builder. Make sure your approved template is compatible. Buttons allow text up to 1,024 characters, 1–3 unique button IDs, and titles up to 20 characters.

For buttons, `fallbackOnClosedWindow: true` with a configured template permits fallback only after an explicit closed-window rejection (`131047` / `OUTSIDE_24H_WINDOW`). It does not turn timeouts, missing message IDs, or unrelated errors into a second send.

Output: `messageId`, `providerMessageId`, `conversationId`, and `reference`. A confirmed provider ID establishes send acceptance; delivery and reading are separate status events. Templates, opt-in/consent requirements, and provider limits still apply.

### Generate with a model — `llm`

Configure `provider`, `model`, `prompt`, optional `instructions`, `providerName`, `temperature`, `maxTokens`, and `output` (`text` or `json`). Use variables in the prompt to pass selected context. Output includes `text`; JSON mode also exposes parsed `json`. An invalid JSON response fails parsing.

Use for summarization, classification, or extraction. This is a bounded model call, not an autonomous agent loop. Model calls are real in test mode and can incur cost; validate generated fields before business side effects.

### Search knowledge — `knowledge.search`

Set `knowledgeBase`, `query`, optional `topK` (up to 50), and `minScore`. Output includes `count`, `results`, and a combined `context` string. Pass selected context to an LLM or use results in explicit rules. Search is real in test mode; it does not itself generate an answer.

### Call agent — `agent`

Submit a request through an existing active HTTP trigger in the same workspace using `triggerId`. With `action.body`, send that explicit body plus automation identifiers. Without it, the block forwards the incoming body and includes available event data and summarized step results under `automation`.

Output includes the trigger's admission `status` and `response`. It is not a guarantee that the agent's full conversation has finished. Test mode simulates submission. The target uses its normal trigger routing: avoid routing it back into the same automation and creating a cycle.

## Control flow

### If — `if`

Evaluate `action.when`, then execute either `then` or `else`. Output identifies the selected branch. Combine rules with `match: "all"` or `"any"`. Use a step's top-level `when` to skip that one step instead of creating two branches.

### For each — `foreach`

Set `items` to a selector resolving to an array, such as `body:contacts`, and place child actions in `steps`. Items execute **sequentially**, up to 100 items. For a loop keyed `contacts`, children can read `steps:contacts.item` and `steps:contacts.index`. The final loop output includes the items and count, not an automatically aggregated list of child outputs.

Iteration records include their index. Retry checkpoints can resume completed work, but a crash around an external effect still requires idempotency; see [operations](https://docs.runflow.ai/automations/testing-and-operations.md).

### Parallel — `parallel`

Run 1–8 independent child actions with `concurrency` from 1 to 4. Each child receives an isolated view of the context that existed before the group. Sibling outputs become available only after the group joins. Use the next step to combine results.

Parallel children must be ordinary actions, not If, For each, Return, or another Parallel. Do not parallelize steps that depend on each other's output or update the same record. The group waits for active children; failure is not rollback of side effects already performed. Group output includes `count`.

### Return — `return`

End the current section successfully without running later steps. It does not set a custom synchronous response to the original webhook caller. Inside a loop or conditional, it exits the section, not just that nested block. Use it for an explicit no-op, such as an ineligible record or a status without correlation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.