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 names are case-sensitive and may contain letters, numbers, and underscores. Spaces are not allowed.
Valid examples
{{topic}}
{{user_email}}
{{MAX_TOKENS}}
{
"userPrompt": "Write a 200-word blog post about {{topic}} aimed at {{audience}}."
}
{{variable_name}} token with the supplied value before the node executes.
Types of variables
iBlueprint supports two kinds of variables that work together:
Runtime variables
Environment 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.
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.Open Blueprint settings
In the Blueprint editor, click the Settings tab in the left sidebar.
Add an environment variable
Under Environment variables, click Add variable. Enter a name (e.g. OPENAI_API_KEY) and its value.
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.
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.
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:
Open the Variables panel
In the Blueprint editor, click the Variables icon in the left toolbar (or press V).
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
Use the variable in nodes
Type {{ inside any node configuration field to see an autocomplete list of defined variables.
Providing a default value lets you run the Blueprint from the editor without filling in the variables form every time — useful during development.
Passing variables at execution time
Via the API
Include the variables key in the request body when calling the execute endpoint:
{
"blueprintId": "bp_01j3k9m2n4p5q6r7s8t",
"variables": {
"topic": "renewable energy",
"audience": "high school students",
"word_count": 200
}
}
Via the CLI
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:
iBlueprint resolves these references after each node completes, so every downstream node has access to all prior outputs.
Output references are read-only — you cannot assign a new value to a node’s output from within a configuration field.
