Variables and Environments

Using variables

Insert values into requests with `{{name}}` tokens and see where each value comes from.

Overview

A variable is a named value you write into a request as {{name}}. When you send the request, Relay replaces each token with the variable's value. Define a base URL, an API key or an ID once, and every request that uses it picks up a change straight away.

You can define variables globally, on a workspace, in an environment, on a collection and on a folder. Requests can't define their own variables; they use the ones from the levels around them.

Write variables in a request

Write a token wherever you'd write the value:

GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{token}}

Tokens work in the URL, query parameter and header names and values, the body, authentication fields, and a WebSocket request's subprotocols and messages.

Variable names are case-sensitive, so {{Token}} and {{token}} are different variables. Names can contain letters, digits, underscores, periods and hyphens, and can start with $. Spaces inside the braces are allowed, so {{ token }} works too.

A token whose variable isn't defined is sent as written, braces included.

Define variables

Each level has its own place to edit its variables:

LevelWhere to edit it
GlobalsIn the Workspaces window, select Globals and click Variables.
WorkspaceIn the Workspaces window, select the workspace, click Variables and choose Default from the menu at the bottom.
EnvironmentIn the Workspaces window, select the workspace, click Variables and choose the environment from the menu at the bottom.
Collection or folderControl-click it in the sidebar and choose Edit Variables….

To open the Workspaces window, click the workspace menu at the top of the sidebar and choose Edit Workspaces….

In each table, click Add Variable, then enter a name and a value. Deselect a row's checkbox to turn the variable off without deleting it. A row that's turned off or has no name is ignored. An empty value is valid: the token becomes an empty string.

Understand which value wins

When several levels define the same name, the one closest to the request wins. From highest to lowest priority:

  1. The request's folders, from the innermost out.
  2. The workspace's active environment.
  3. The request's collection.
  4. The workspace.
  5. Globals.

For example, if the workspace defines baseUrl as https://api.example.com and the active Staging environment defines it as https://staging.example.com, requests use the staging URL. Choose No Environment, and they use the workspace's URL again.

Drafts aren't in a collection, so they use only their workspace's environment, the workspace's variables and globals.

Two other kinds of values sit outside these levels:

  • Values a script sets with relay.variables.set take priority over every level, but only for the send in progress. For more information, see Reading and writing variables in scripts.
  • Dynamic variables, such as {{$guid}}, come after every level, so a variable you define with the same name wins. For more information, see Generating dynamic values.

Use variables inside variables

A variable's value can contain other tokens:

NameValue
hostapi.example.com
baseUrlhttps://{{host}}/v2

Relay expands tokens inside values too, so {{baseUrl}} becomes https://api.example.com/v2. Each nested token is looked up from the top of the order again, so a folder can override host and change baseUrl for every request inside it.

A value that refers back to itself, directly or through other variables, or that nests too deeply, can't be expanded. Its token is sent as written, and the Variables list shows the value in orange.

See where a value comes from

Hold the pointer over a token in a field to see its value and where it's defined, such as the environment's or collection's name, or Global. The tooltip shows the fully expanded value. Tokens for undefined variables show no tooltip.

To see every variable a request can use, click the Variables button in the bar at the bottom of the request editor. The list shows each variable's name, the value that wins and an icon for the level it comes from. In the list:

  • Click a name to copy its token, such as {{baseUrl}}, to paste into a field.
  • Click the … button beside a variable and choose Copy Key, Copy Value or Edit Variable….
  • At the bottom, click a level, such as the workspace, environment, collection or a folder, to edit its variables.

A secret variable without a value on this Mac shows "No value on this Mac". For more information, see Keeping secrets on your Mac.

See Also