Environment Variables

Environment Variables

Environments let you switch between different API configurations (development, staging, production) without changing your requests.

---

Quick Start

1. Click the environment dropdown in the header bar
2. Select Manage Environments
3. Add variables:
   • baseUrl → http://localhost:3000
   • apiKey → dev-key-12345
4. Use {{baseUrl}} and {{apiKey}} in your requests
5. Switch environments with Ctrl+E

---

Environment Files

Environments are stored as YAML files in your collection:

.apiark/
└── environments/
    ├── development.yaml
    ├── staging.yaml
    └── production.yaml

Format

# .apiark/environments/development.yaml
name: Development
variables:
  baseUrl: http://localhost:3000
  apiVersion: v2
  apiKey: dev-key-12345
  timeout: "5000"
secrets:
  - accessToken      # Value stored in .env, not here
  - adminPassword

# .apiark/environments/production.yaml
name: Production
variables:
  baseUrl: https://api.example.com
  apiVersion: v2
  apiKey: prod-key-67890
  timeout: "30000"
secrets:
  - accessToken
  - adminPassword

---

Variable Types

Regular Variables

Stored in the YAML file, visible in Git, shareable with your team.

variables:
  baseUrl: https://api.example.com
  apiKey: public-key-12345

Secret Variables

Values stored in .env file (gitignored), masked in the UI by default.

secrets:
  - accessToken
  - dbPassword

# .apiark/.env
accessToken=eyJhbGciOiJIUzI1NiIs...
dbPassword=super-secret-password

Secrets are never committed to Git, never written to history, and never logged.

Global Variables

Apply to ALL collections. Managed in Settings → Global Environment.

---

Using Variables

In URLs

{{baseUrl}}/api/users/{{userId}}

In Headers

headers:
  Authorization: "Bearer {{accessToken}}"
  X-API-Key: "{{apiKey}}"

In Body

{
  "email": "{{userEmail}}",
  "token": "{{accessToken}}"
}

In Scripts

// Read
const url = ark.env.get("baseUrl");

// Write
ark.env.set("userId", "usr_123");

// Delete
ark.env.unset("tempVar");

// Get all
const vars = ark.env.toObject();

---

Dynamic Variables

Built-in variables that generate values on each request:

Variable	Example Output	Description
{{$uuid}}	550e8400-e29b-41d4-a716-446655440000	Random UUID v4
{{$timestamp}}	1710345600	Unix timestamp (seconds)
{{$timestampMs}}	1710345600000	Unix timestamp (milliseconds)
{{$isoTimestamp}}	2026-03-13T12:00:00.000Z	ISO 8601 timestamp
{{$randomInt}}	742	Random integer 0-1000
{{$randomFloat}}	0.8234	Random float 0-1
{{$randomString}}	aB3dE5fG7hI9jK1m	Random 16-char alphanumeric
{{$randomEmail}}	user_abc123@example.com	Random email address

Usage

url: "{{baseUrl}}/api/users"
headers:
  X-Request-ID: "{{$uuid}}"
  X-Timestamp: "{{$isoTimestamp}}"
body:
  type: json
  content: |
    {
      "email": "{{$randomEmail}}",
      "name": "Test User {{$randomInt}}"
    }

---

Variable Scoping & Precedence

Variables are resolved in this order (later overrides earlier):

1. Global variables (apply to all collections)
2. Collection defaults (from apiark.yaml)
3. Active environment (from environments/*.yaml)
4. Folder variables (from _folder.yaml)
5. Request-level variables (set in scripts)
6. Dynamic variables ({{$uuid}}, etc.)

---

.env File Support

ApiArk auto-loads .env files from the collection root:

# .apiark/.env
DATABASE_URL=postgres://localhost:5432/mydb
API_SECRET=my-secret-key
JWT_TOKEN=eyJhbGciOiJIUzI1NiIs...

These values are available as {{DATABASE_URL}}, {{API_SECRET}}, etc.

The .env file is auto-added to .gitignore when you create a collection.

---

Variable Quick-View

Click the eye icon next to any variable reference in the URL bar or editors to peek at the current resolved value without switching to the environment panel.

---

Tips

• Use environments for per-stage config: Base URLs, API keys, feature flags
• Use secrets for sensitive values: Tokens, passwords, private keys
• Use scripts for dynamic values: Computed values, chained request data
• Use .env for machine-specific config: Local DB URLs, personal tokens
• Name clearly: baseUrl not url, adminToken not token