# Flow Variables

A **Flow Variable** is a named placeholder scoped to a single Agent's [Flow](/docs/concepts/flows). You capture or set its value at one node and reference it later as `{VARIABLE_NAME}` in any interpolable text field of the same flow.

Flow variables are scoped to **one Agent**. They are not visible to other agents and not shared with [Workflow Variables](/docs/concepts/workflow-variables).

## Identity

| Field | Type | Notes |
|  --- | --- | --- |
| `id` | number | Use as `variableId`. |
| `name` | string | Snake-case by convention. Used inside `{NAME}` interpolation tags. |
| `description` | string? |  |
| `status` | enum | `ACTIVE` · `INACTIVE` · `ARCHIVED`. |
| `pattern` | string? | Optional regex pattern. Used to validate captured values. |
| `defaultValue` | string? | Value used when the variable has not been set yet. |
| `isDefault` | boolean | `true` for variables that ship with the platform (e.g. `customer_name`). |
| `assistantId` | string | Owning agent (UUID). |
| `createdAt` | string | ISO timestamp. |
| `updatedAt` | string | ISO timestamp. |


## Where they interpolate

Reference variables in text fields as `{VARIABLE_NAME}`. The name must match **exactly**, including case.

Interpolable text fields inside a Flow:

- **API** node: `url`, `headers[].value`, `parameters[].value`, `body`
- **Say AI**: `message`, `prompt`
- **Response AI**: `instructions`
- **Tools AI**: `instructions`
- **Conditional Routing AI**: `conditions[].expression`
- **Dynamic Tables**: `rowId`, `search`, `rowData` values


## Naming

- Use snake_case (e.g. `customer_name`, `order_id`).
- Must be unique within the agent. Use the `check-name` endpoint to test availability before creating.
- Pick a name you can use as `{name}` directly in copy.


## Operations

| Verb | Path |
|  --- | --- |
| `GET` | `/public/v1/agents/{agentId}/variables` |
| `POST` | `/public/v1/agents/{agentId}/variables` |
| `GET` | `/public/v1/agents/{agentId}/variables/{variableId}` |
| `PUT` | `/public/v1/agents/{agentId}/variables/{variableId}` |
| `DELETE` | `/public/v1/agents/{agentId}/variables/{variableId}` |
| `GET` | `/public/v1/agents/{agentId}/variables/all` |
| `GET` | `/public/v1/agents/{agentId}/variables/check-name?name=...` |


All endpoints require a `USER` API key. Full details under the **Flow Variables** tag in the **[API Reference](/reference/openapi)**.

## CLI


```bash
frontline agents variables list --table
frontline agents variables create --name customer_name --description "Captured customer name"
frontline agents variables check-name customer_name
frontline agents variables update 123 --name customer_name --pattern "^[A-Za-z ]+$"
```