.http file syntax cheat sheet

A .http (or .rest) file is a plain-text list of HTTP requests. The format is shared by the REST Client extension for VS Code and the JetBrains HTTP Client, and it is the format Plainwire reads and writes. This page is a working reference: every snippet below is a valid file you can paste and send.

If something on this page does not behave as described in Plainwire, that is a bug or a gap; please report it.

Requests and separators

A request starts with a request line: method, URL and an optional HTTP version. If you leave out the method, it is GET. Separate requests in the same file with a line starting with ###; any text after the hashes becomes the request’s title.

GET https://api.example.com/users/1

### Create a user
POST https://api.example.com/users HTTP/1.1

### Method omitted means GET
https://api.example.com/health

Long query strings can be split over several lines. Each continuation line starts with ? or &, indented under the request line:

GET https://api.example.com/orders
    ?status=open
    &page=2
    &pageSize=50

Comments

Lines starting with # or // are comments. A comment of the form # @name value is metadata for the request below it; the most useful is @name, which you need for chaining.

# Fetch the current user. Needs a token.
// This is also a comment
# @name me
GET https://api.example.com/me

Headers and auth

Headers follow the request line, one Name: value per line, until the first blank line.

GET https://api.example.com/reports
Accept: application/json
Accept-Language: en
Authorization: Bearer {{token}}

Basic auth is an Authorization header with user:password encoded in base64. The encoded form below (for user:pass) works in every client; REST Client also accepts Basic user:pass and encodes it for you.

GET https://api.example.com/admin
Authorization: Basic dXNlcjpwYXNz

Bodies

The body starts after the blank line that ends the headers and runs until the next ###. Set Content-Type to say what it is.

JSON

POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "roles": ["admin"]
}

Plain text or XML

PUT https://api.example.com/notes/7
Content-Type: text/plain

Remember to rotate the staging keys.

URL-encoded form

Write the fields as one string, or one per line with each extra line starting with &:

POST https://api.example.com/login
Content-Type: application/x-www-form-urlencoded

username=ada
&password={{password}}
&remember=true

Bodies from files

A body line starting with < followed by a path sends that file’s contents. Relative paths are resolved from the .http file’s folder. REST Client additionally supports <@, which replaces {{variables}} inside the file before sending.

POST https://api.example.com/import
Content-Type: application/json

< ./fixtures/new-order.json

### Variables inside the file are substituted (REST Client)
POST https://api.example.com/import
Content-Type: application/json

<@ ./fixtures/order-template.json

File variables

Define a variable on its own line with @name = value and use it anywhere with {{name}}. Variables can reference other variables. They apply to the whole file, so they are usually placed at the top.

@host = https://api.example.com
@apiVersion = v2
@baseUrl = {{host}}/{{apiVersion}}

###
GET {{baseUrl}}/products

Environments

Environments hold values that differ between local, staging and production. Plainwire reads three sources.

http-client.env.json (commit this)

The JetBrains layout: one object per environment name. Put it next to your .http files.

{
  "local": {
    "baseUrl": "http://localhost:3000",
    "user": "dev@example.com"
  },
  "staging": {
    "baseUrl": "https://staging.example.com",
    "user": "qa@example.com"
  }
}

http-client.private.env.json (gitignore this)

Same shape, for secrets. Values here are merged into the environment of the same name. Add the file to .gitignore.

{
  "local":   { "password": "local-only-password" },
  "staging": { "password": "replace-me" }
}

The rest-client.environmentVariables setting

REST Client keeps environments in VS Code settings (for a project, .vscode/settings.json). Values under $shared are available in every environment.

{
  "rest-client.environmentVariables": {
    "$shared": { "apiVersion": "v2" },
    "local":   { "baseUrl": "http://localhost:3000" },
    "staging": { "baseUrl": "https://staging.example.com" }
  }
}

System variables

Built-in dynamic values start with $. Arguments follow REST Client’s syntax.

VariableValue
{{$guid}}A new random UUID on each send.
{{$timestamp}}The current Unix time in seconds.
{{$randomInt 1 100}}A random integer from the first number up to (not including) the second.
{{$datetime iso8601}}The current UTC date and time; rfc1123 is the other standard format.
{{$processEnv HOME}}An environment variable of the editor process.
{{$dotenv API_KEY}}A value from a .env file next to the .http file.
POST {{baseUrl}}/events
Content-Type: application/json
X-Request-Id: {{$guid}}
X-Api-Key: {{$dotenv API_KEY}}

{ "at": "{{$datetime iso8601}}", "seq": {{$randomInt 1 1000}} }

Request chaining

Name a request with # @name, send it, then read its response in later requests with {{name.response.body.$.path}}. The part after body. is a JSONPath expression into the JSON response.

### Log in
# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{ "email": "{{user}}", "password": "{{password}}" }

### Use the token
GET {{baseUrl}}/orders
Authorization: Bearer {{login.response.body.$.token}}

### Use a nested value
GET {{baseUrl}}/users/{{login.response.body.$.user.id}}
Authorization: Bearer {{login.response.body.$.token}}

If the named request has not been sent yet in this session, Plainwire sends it first automatically, then the dependent one.

Importing another .http file

Put shared variables and a login request in one file and import it wherever you need them. The path is relative to the importing file. Both the httpYac form and the JetBrains form work:

# api/orders.http
# @import ../shared/auth.http

### List orders
GET {{baseUrl}}/orders
Authorization: Bearer {{login.response.body.$.token}}

Variables of the imported file are available, and its named requests can be chained: the login above is sent first, with auth.http’s own variables, and remembered for the session. The importing file’s own variables win over imported ones. More in sharing variables and a login between .http files.

Per-request settings

Metadata lines above the request line change how one request is sent:

### Slow report
# @timeout 2m
# @no-redirect
# @no-cookie-jar
# @insecure
GET https://localhost:8443/report

# @timeout takes milliseconds or s/m (5000, 5s, 2m). # @no-redirect returns a 3xx as it is, # @no-cookie-jar sends the request without the cookie jar (cookies set by earlier responses are otherwise sent, like in a browser), and # @insecure accepts a self-signed certificate.

Server-sent events

A response with Content-Type: text/event-stream is shown event by event while it arrives. It ends when the server closes it, when you press Stop, at the timeout, or after # @max-events events; all four keep what arrived. See server-sent events in VS Code.

### Stream a reply
# @max-events 20
# @assert events[-1].data == "[DONE]"
POST {{baseUrl}}/v1/chat/stream
Content-Type: application/json

{ "prompt": "Say hello", "stream": true }

Quick reference

SyntaxMeaning
### / ### TitleStart a new request, optionally titled
METHOD url HTTP/1.1Request line; method and version optional
?a=1, &b=2Query continuation lines
Name: valueHeader (until the first blank line)
#, //Comment
# @name loginName a request for chaining
@var = valueFile variable
{{var}}Use a file, environment or system variable
< ./fileBody from a file
{{login.response.body.$.x}}Value from a named request’s response
# @timeout 5sTime limit for this request
# @max-events 3Close a server-sent events stream after 3 events
# @import ./shared.httpUse another file’s variables and named requests (JetBrains: import ./shared.http)

Coming from another tool? See cURL to .http, Postman to .http and Thunder Client to .http.