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

# Blueprint variables: pass dynamic data at runtime

> Define variables in your iBlueprint Blueprints and inject dynamic values at execution time using double-brace syntax to keep workflows reusable and configuration-free.

Variables make your iBlueprint Blueprints reusable. Instead of hardcoding values like usernames, API keys, or article text directly into node configurations, you define named placeholders and supply the actual values when you run the Blueprint. Every node configuration field that accepts text also accepts variable references, so a single Blueprint can power many different use cases.

## Variable syntax

Reference a variable anywhere in a node configuration using double curly braces:

```
{{variable_name}}
```

Variable names are case-sensitive and may contain letters, numbers, and underscores. Spaces are not allowed.

**Valid examples**

```
{{topic}}
{{user_email}}
{{MAX_TOKENS}}
```

**In a node configuration field**

```json theme={null}
{
  "userPrompt": "Write a 200-word blog post about {{topic}} aimed at {{audience}}."
}
```

When the Blueprint runs, iBlueprint replaces each `{{variable_name}}` token with the supplied value before the node executes.

## Types of variables

iBlueprint supports two kinds of variables that work together:

<Tabs>
  <Tab title="Runtime variables">
    Runtime variables are values you pass each time you trigger a Blueprint execution. They are transient — they exist only for the duration of that run and are not stored on the Blueprint itself.

    Use runtime variables for content that changes per run: user-provided text, dynamic IDs, dates, or any input that should not be persisted.

    **How to supply them**

    * **Web UI**: Fill in the variables form that appears when you click **Run**.
    * **API**: Include a `variables` object in your execute request body.
    * **CLI**: Pass a JSON string with the `--inputs` flag.
  </Tab>

  <Tab title="Environment variables">
    Environment variables are stored on the Blueprint and are available to every execution without needing to be passed at run time. They are ideal for secrets, API keys, and configuration that remains constant across runs.

    <Steps>
      <Step title="Open Blueprint settings">
        In the Blueprint editor, click the **Settings** tab in the left sidebar.
      </Step>

      <Step title="Add an environment variable">
        Under **Environment variables**, click **Add variable**. Enter a name (e.g. `OPENAI_API_KEY`) and its value.
      </Step>

      <Step title="Reference in node configs">
        Use `{{OPENAI_API_KEY}}` in any node configuration field. The value is substituted at execution time without being exposed in the Blueprint map.
      </Step>
    </Steps>

    <Warning>
      Environment variable values are encrypted at rest, but anyone with editor access to the Blueprint can overwrite them. Do not share Blueprint editor access with untrusted users if it holds production secrets.
    </Warning>
  </Tab>
</Tabs>

## Defining variables in the editor

You can declare expected runtime variables directly on the Blueprint so the web UI knows what inputs to prompt for:

<Steps>
  <Step title="Open the Variables panel">
    In the Blueprint editor, click the **Variables** icon in the left toolbar (or press `V`).
  </Step>

  <Step title="Add a variable definition">
    Click **+ Add variable** and fill in:

    * **Name** — the identifier used in `{{variable_name}}` syntax
    * **Type** — `string`, `number`, `boolean`, or `json`
    * **Default value** (optional) — used when no value is supplied at run time
    * **Description** (optional) — shown as a hint in the run dialog
  </Step>

  <Step title="Use the variable in nodes">
    Type `{{` inside any node configuration field to see an autocomplete list of defined variables.
  </Step>
</Steps>

<Tip>
  Providing a default value lets you run the Blueprint from the editor without filling in the variables form every time — useful during development.
</Tip>

## Passing variables at execution time

### Via the API

Include the `variables` key in the request body when calling the execute endpoint:

```json theme={null}
{
  "blueprintId": "bp_01j3k9m2n4p5q6r7s8t",
  "variables": {
    "topic": "renewable energy",
    "audience": "high school students",
    "word_count": 200
  }
}
```

The values can be strings, numbers, booleans, arrays, or nested objects. iBlueprint serialises non-string types to JSON before substituting them into text fields.

### Via the CLI

```bash theme={null}
iblueprint execute bp_01j3k9m2n4p5q6r7s8t \
  --inputs '{"topic":"renewable energy","audience":"high school students"}'
```

### Via the web UI

Click **Run** on any Blueprint. If the Blueprint has declared variables, the run dialog displays a form with a field for each one. Fill in the values and click **Execute**.

## Referencing node output

In addition to named variables, you can pass the output of any upstream node into a downstream node's configuration using the node's output reference:

```
{{nodes.node_id.output}}
```

iBlueprint resolves these references after each node completes, so every downstream node has access to all prior outputs.

<Note>
  Output references are read-only — you cannot assign a new value to a node's output from within a configuration field.
</Note>