File format reference

A .http / .rest file holds one or more requests separated by ###. Everything before the first ### belongs to the first request.

@baseUrl = http://localhost:8184        # file variable (applies to the whole file)

### Login                               # separator; the text is the title
# @name login                           # directives (comment lines starting with @)
# @tag auth
# @timeout 5s
POST {{baseUrl}}/login HTTP/1.1         # request line; method defaults to GET, version is optional
Content-Type: application/json          # headers until the first blank line

{"username": "demo"}                    # body until the first `??` line or the next ###

?? status == 200                        # assertions

Comments

Lines starting with # or // are comments in the preamble and header section. Inside a body they are part of the body.

Request names

The name is, in order of precedence: # @name x, the ### Title text if it is a plain word ([A-Za-z0-9_-]+), a slug of the title (### Users list becomes users-list), or request-N. Names must be unique in a file; they are used by --only, restbook curl, response references and saved response files.

Directives

Directive	Effect
`# @name x`	Request name (letters, digits, `_`, `-`).
`# @tag a, b`	Tags, matched by `--only`.
`# @timeout 5s`	Per-request timeout: `500ms`, `5s`, `2m` or plain seconds.
`# @no-redirect`	Do not follow redirects for this request.
`# @skip`	Reported as skipped, never sent. Requests that reference its response fail.
`# @after a, b`	Run after `a` and `b` even without a data dependency. Needed with `-j` when requests are order-sensitive (for example "delete" then "gone").

Unknown directives are a parse error, so typos do not pass silently.

URLs

A URL may continue on following indented lines that begin with ? or &:

GET {{baseUrl}}/notes
    ?page=1
    &per_page=5

Bodies

Raw / JSON / text: the lines up to the first ?? line, with trailing blank lines removed.
Whole-body file include: a body that is only < ./path/to/file is replaced by the file's bytes. Paths are relative to the .http file.
application/x-www-form-urlencoded: lines are joined without separators, so continuation lines should start with &.
multipart/form-data; boundary=B: parts start with --B, end with --B--. Each part has Content-Disposition: form-data; name="..." (and optional filename="...", Content-Type). A part whose content is a single < ./file line sends that file; its content type is guessed from the extension if not given.
GraphQL: add X-REQUEST-TYPE: GraphQL. The body is the query, then a blank line, then optional variables as JSON. It is sent as {"query": ..., "variables": ...} with Content-Type: application/json (the marker header is not sent).

Variables

See design.md for resolution order. Syntax: {{name}}.

Form	Meaning
`{{name}}`	`--var` value, else file variable (`@name = value`), else environment value.
`{{$env.NAME}}`	OS environment variable (error if unset). The value is masked in dry-run output.
`{{$uuid}}`	Random UUID v4 (`$guid` is an alias).
`{{$timestamp}}` / `{{$timestamp +1h}}`	Unix seconds, optionally offset.
`{{$randomInt 1 100}}`	Inclusive random integer; `{{$randomInt}}` is 0 to 1000.
`{{$datetime iso8601}}` / `rfc1123` / `timestamp`, optional offset	`{{$datetime iso8601 +1d}}`. Offsets: `ms s m h d w`, signed.
`{{login.response.body.$.token}}`	JSONPath into a previous response body.
`{{login.response.body}}`	The whole response body text.
`{{login.response.headers.Location}}`	Response header (case-insensitive).
`{{login.response.status}}`	Status code.

Arrays and objects interpolate as compact JSON, booleans as true/false, null as null.

JSONPath subset

$, .key, ['key'], ["key"], [n], [-n], [*], .*, ..key (recursive), and a .length pseudo-property on arrays, strings and objects (only when there is no real length key). Filters and slices are not supported.

Environments

http-client.env.json next to the .http file (or in the current directory):

{
  "$shared": { "username": "demo" },
  "dev":     { "baseUrl": "http://127.0.0.1:8184" },
  "staging": { "baseUrl": "https://staging.example.com" }
}

http-client.private.env.json has the same shape and is merged on top; keep it out of version control. Values from the private file are masked in dry-run output, saved requests and restbook curl --mask. Select with --env dev; $shared always applies.