How to Use Variable Types in Bruno v4: A Complete Guide

Variables are how Bruno keeps your API collections flexible. Instead of hard-coding a base URL, a token, or a timeout in every request, you define a variable once and reference it everywhere. Bruno v4 takes this further: variables can now be typed. A timeout can be a number, a feature flag can be a boolean, and a config block can be a full object not just strings. This guide covers the full variable system in Bruno and dives into the typed variable support introduced in v4, including the breaking change you need to know about before upgrading.

What Are Variables in Bruno

A variable is a named value that Bruno substitutes into your requests at runtime. You reference a variable using double curly braces:

https://{{baseUrl}}/users/{{userId}} 

When Bruno runs that request, {{baseUrl}} and {{userId}} are replaced with their current values. If you change the base URL for staging, you update it in one place instead of every request that uses it.

Variables can appear in:

• Request URLs, headers, query parameters, and body
• Authentication fields (tokens, credentials)
• Script values passed between requests
• Pre-request and post-request scripts

Variable Types and Where They Live

Bruno has eight distinct variable categories. Each has a different scope and a different place it is defined:

Data Types in Bruno v4 (Breaking Change)

Breaking change in v4.0.0: Bruno now supports typed variables. Collections that use @type(...) annotations will not parse in Bruno versions older than v4.0.0. If your team has members on v3, coordinate the upgrade before using typed variables in shared collections.

Before v4, every variable was a string. That meant sending a timeout value of 30 in a JSON body would arrive as "30" (a string) instead of the number 30. You had to cast it in a script. v4 removes that limitation.

Starting with v4.0.0, variables support four data types:

Backward compatible: Existing .bru files and environments that use plain string values continue to work without any changes. The @type annotation is only written when a non-string type is used.

YAML File Syntax for Typed Variables

In .yml files (used for workspace-level and environment configs), each typed variable is an object with a type field and a data field. Plain strings continue to use the flat name: value form — no change needed there.

runtime:
  variables:
    - name: timeout
      value:
        type: number
        data: "30"

    - name: debug
      value:
        type: boolean
        data: "true"

    - name: config
      value:
        type: object
        data: '{"host":"localhost","port":8080}'

    - name: baseUrl
      value: https://api.example.com
        # plain string — no type field needed

BRU vs YAML at a glance

BRU File Syntax for Typed Variables

In .bru files, you declare a type by placing the annotation on the line immediately above the variable. Object values use a triple-quote (''') block to hold multi-line JSON.

vars:pre-request {
  @number
  timeout: 30

  @boolean
  debug: true

  baseUrl: https://api.example.com
}

vars:pre-request {
  @object
  config: '''
    {
      "host": "localhost",
      "port": 8080
    }
  '''
}

A full pre-request vars block combining all four types looks like this:

vars:pre-request {
  baseUrl: https://api.example.com   // string — no annotation

  @number
  timeout: 30

  @boolean
  featureFlag: true

  @object
  dbConfig: '''
    {
      "host": "localhost",
      "port": 5432
    }
  '''
}

The annotation must be on the line immediately above the variable, with no blank line between them. A blank line between @number and the variable name will cause it to be treated as a string.

Setting Typed Variables from Scripts

You can set typed variables from pre-request and post-request scripts using the same scripting API you already know. Bruno infers the type from the JavaScript value you pass and writes the correct annotation automatically — you do not need to specify a type manually.

// number — written with @number annotation
bru.setEnvVar("timeout", 30)

// boolean — written with @boolean annotation
bru.setEnvVar("debug", true)

// object — written with @object annotation
bru.setEnvVar("config", { host: "localhost", port: 8080 })

// string — written as plain string (no annotation)
bru.setEnvVar("baseUrl", "https://api.example.com")

When Bruno reads the variable back on the next request run, timeout resolves as a JavaScript number and config resolves as an object — not strings that need parsing. The type is preserved across runs.

Typed values work across all variable scopes from scripts. The same inference applies to:

bru.setEnvVar("retries", 3)
bru.setEnvVar("verbose", false)

bru.setVar("userId", 101)
bru.setVar("isAdmin", true)

Debugging variables in the console

To inspect a variable value and its resolved type during a run, use the bru.get[Type]Var(key) pattern in a script:

// Runtime variable
console.log(bru.getVar('userId'))

// Environment variable
console.log(bru.getEnvVar('timeout'))

// Collection variable
console.log(bru.getCollectionVar('config'))

Prompt variables are not accessible via the Scripting API. They are entered by the user at the moment of the run and are never stored or readable from scripts.

Type Selector in the UI

You do not need to write annotations by hand. In the Vars tab of any request, folder, or environment, each variable row has a type dropdown to the right of the value field. Changing the type in the dropdown writes the correct annotation into the .yml file automatically.

Available options in the dropdown match the four supported types: string, number, boolean, and object. When you select object, the value field expands to accept a JSON block.

Quick Reference

Wrap Up

Variables are the foundation of any well-organised Bruno collection. They keep values in one place, let you switch environments instantly, and flow data between requests through scripts. Bruno v4 extends this with real data types: numbers stay numbers, booleans stay booleans, and objects stay objects — from the file on disk all the way through to the request body, without any casting or parsing in scripts.

The one thing to coordinate before adopting typed variables is the team upgrade: any .bru file with a @number, @boolean, or @object annotation will not open in Bruno versions before v4. Once your team is on v4, you get the full power of typed variables across all scopes, in both the BRU and YAML formats, and with automatic type inference from scripts.