Variables let you parameterize requests — URLs, headers, bodies, assertions. Use ${VAR} syntax anywhere in your YAML files.

Syntax

url: ${BASE_URL}/api/users/${USER_ID}
headers:
  Authorization: Bearer ${API_KEY}

Default Values

Provide fallbacks with :-:

url: ${BASE_URL:-http://localhost:3000}/api/users
headers:
  X-Timeout: ${TIMEOUT:-30}

If BASE_URL is not set, http://localhost:3000 is used.

Resolution Order

Variables resolve in this priority (highest first):

Chain step references: ${step_name.field} — data from previous chain steps
Environment vars from yapi.config.yml — vars defined in the active environment
Shell environment variables — from your OS/shell
Default values — specified with :-

Type Preservation

When ${VAR} is the entire value, the original type is preserved:

body:
  count: ${step.count}          # Stays an integer if count is int
  label: "Count: ${step.count}" # String interpolation

Environment Variable References in Assertions

In assertions, use env.VAR_NAME to compare against environment variables:

expect:
  assert:
    - .owner == env.GITHUB_USER
    - .region == env.AWS_REGION

Variables from Config

Define variables in yapi.config.yml:

yapi: v1
default_environment: local

defaults:
  vars:
    API_VERSION: v1

environments:
  local:
    url: http://localhost:3000
    vars:
      API_KEY: dev_key

Then reference them in request files:

yapi: v1
url: ${url}/api/${API_VERSION}/users
headers:
  X-Api-Key: ${API_KEY}

Env Files

Load variables from .env files:

# yapi.config.yml
environments:
  prod:
    url: https://api.example.com
    env_file: .env.prod

Or per-request:

yapi: v1
env_files:
  - .env.local
url: ${BASE_URL}/api/users