Core Concepts
Once these four designs click, every protocol and scenario that follows is straightforward:
- The three-entity model: how Group / Environment / Request relate
- Environment Pre-URL design: why requests store only relative paths
- The send assembly pipeline: how one Send turns configuration into a real request
- The variable system: where
{{variable}}resolves from, and the three variable layers
The Three-Entity Model
Why is the environment bound to the group instead of each request? A group usually represents "all APIs of one module under one deployment target". Binding at group level means switching environments moves the whole group at once — no per-request edits. If a single request needs a different environment, just put it in a group bound to that environment.
Environment Pre-URL Design
This is the most important — and most misunderstood — design.
Requests store relative paths; environments store base addresses
In traditional tools every request stores a full URL (https://api.example.com/v1/users), so switching to a test environment means batch-replacing domains. This tool flips it:
The scheme decides the protocol and TLS (key!)
Pre-URLs are stored per protocol, but which protocol an entry actually serves is decided by the scheme at the start of the URL. The scheme expresses both "which protocol" and "encrypted or not (TLS)":
| Protocol | Plain scheme | Encrypted scheme |
|---|---|---|
| HTTP | http:// | https:// |
| WebSocket | ws:// | wss:// |
| TCP | tcp:// | tcps:// |
| UDP | udp:// | — |
| gRPC | grpc:// | grpcs:// |
| MQTT | mqtt:// | mqtts:// |
⚠️ Common mistake: a WebSocket base address must be written as
ws:///wss://. If you typehttps://, it is treated as HTTP and the WebSocket request fails for lack of a base address. Keep the protocol line and the scheme consistent.
The Send Assembly Pipeline
Tapping "Send" doesn't fire a socket directly. The pipeline assembles "request + the group's environment + variables" step by step into a real request, and inserts an action chain before and after the network call:
Key points:
- Action chains only run when "execute scripts" is on. Tapping Send in the app runs them by default; automated / MCP sends must opt in explicitly. With scripts off, tokens injected pre-send or encryption simply don't happen — which is exactly why the "no token → 401" negative control in recipes behaves that way.
- Pre-send scripts rewrite the request that is about to go out; post-response scripts rewrite the response you got back. Both can read and write runtime variables.
The Variable System
There are three kinds of "variables" with different scopes. Mixing them up is the most common beginner trap.
What can {{name}} actually resolve?
| Where it's written | Environment variables | Runtime variables | Typical use |
|---|---|---|---|
{{name}} (in URL / params / headers / body) | ✅ | ❌ | Reference environment config, dynamic filling |
| Reading variables inside scripts | ✅ | ✅ | Passing login tokens across requests, etc. |
Mnemonic:
{{}}only sees "configuration-type" variables; scripts can read all three layers. Runtime variables are the "runtime blackboard" — only scripts can scribble on it, and{{}}never looks there.
Why can't {{authToken}} read the token saved at login? Because the login script stored it in the runtime layer, which {{}} does not parse. The correct approach is a pre-send script that reads it and injects the header (see recipes, scenario 1).
Dynamic variables {{$xxx}}
Inside {{}} there is also a set of built-in dynamic variables, generated fresh at each evaluation, usable directly in URL / params / headers / body:
| Variable | Generates |
|---|---|
{{$timestamp}} / {{$timestampMs}} | Unix timestamp in seconds / milliseconds |
{{$isoTimestamp}} | ISO8601 UTC |
{{$uuid}} / {{$guid}} | UUID v4 |
{{$randomInt}} / {{$randomInt min,max}} | Random integer (default 0..1000) |
{{$randomBoolean}} {{$randomFullName}} {{$randomEmail}} {{$randomPhoneNumber}} {{$randomIpv4}} {{$randomIpv6}} {{$randomUrl}} {{$randomColor}} {{$randomHexadecimal}} {{$randomAlphaNumeric}} {{$randomCity}} {{$randomCountry}} {{$randomDateRecent}} {{$randomPrice}} {{$randomWord}} {{$randomLorem}} {{$randomCompanyName}} etc. | Assorted random sample data |
Example: GET /echo?ts={{$timestamp}}&u={{$uuid}} — in practice every send replaces ts/u with fresh real values.
Summary
- Requests store path fragments; environments supply base addresses per protocol via Pre-URLs; the scheme decides protocol + TLS.
- Sending is an assembly pipeline: join URL → interpolate → transport settings → pre-send chain → network → post-response chain.
- Variables come in three layers:
{{}}reads configuration-type variables, scripts read all three; pass tokens with scripts, not{{}}.
Next: scripting →