.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.
| Variable | Value |
|---|---|
{{$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
| Syntax | Meaning |
|---|---|
### / ### Title | Start a new request, optionally titled |
METHOD url HTTP/1.1 | Request line; method and version optional |
?a=1, &b=2 | Query continuation lines |
Name: value | Header (until the first blank line) |
#, // | Comment |
# @name login | Name a request for chaining |
@var = value | File variable |
{{var}} | Use a file, environment or system variable |
< ./file | Body from a file |
{{login.response.body.$.x}} | Value from a named request’s response |
# @timeout 5s | Time limit for this request |
# @max-events 3 | Close a server-sent events stream after 3 events |
# @import ./shared.http | Use 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.