Syntax

.http File Syntax Reference

File Structure

A .http file contains one or more request blocks, separated by ### delimiters. Each block has:

[file-level @var definitions]
[file-level import/run directives]

### Request Name
[block-level @var definitions]
[<<prompt variables]
[pre-request script: < {% ... %}]
METHOD URL [HTTP/version]
Header-Name: Value
...

[request body]

[post-request assertion: > {% ... %}]

Request Block Separator

### Request Name

Three ### characters followed by an optional name. Names are used for symbol navigation and cross-request references.

If omitted, the block is unnamed.

Request Line

METHOD URL [HTTP/version]

Supported methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE, CONNECT, SCRIPT

Examples:

GET https://api.example.com/users
POST https://api.example.com/users HTTP/1.1
PUT https://api.example.com/users/1
DELETE https://api.example.com/users/1

Headers

Standard Key: Value format:

Content-Type: application/json
Authorization: Bearer {{token}}
Accept: application/json
X-Custom-Header: value

Body

Separated from headers by a blank line.

JSON Body

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

{
  "name": "John",
  "email": "john@example.com"
}

URL-Encoded Form Data

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

username=admin&password=secret

Multipart Form Data

POST https://api.example.com/upload
Content-Type: multipart/form-data; boundary=boundary123

--boundary123
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

< ./photo.jpg
--boundary123
Content-Disposition: form-data; name="description"

Profile photo
--boundary123--

File Include

Place file contents inline:

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

< ./payload.json

Supports ~ for home directory and relative paths (relative to the .http file).

Comments

# This is a comment
-- This is also a comment

Comments can appear anywhere. Commented-out prompt variables are ignored:

# <<auth_token

Variable Definitions

See Variables for full details.

File-Level

@base_url = https://api.example.com
@token = my-secret-token

Block-Level (overrides file-level)

### Update User
@base_url = https://staging.api.example.com
PUT {{base_url}}/users/1

Multi-Line

@headers_block =>>>
Content-Type: application/json
Authorization: Bearer {{token}}
<<<

Variable References

GET {{base_url}}/users/{{user_id}}
Authorization: Bearer {{token}}

Magic Variables

Variable	Description
{{$timestamp}}	Current Unix timestamp
{{$uuid}}	Random UUID v4
{{$date}}	Current date string
{{$randomInt}}	Random integer

Cross-Request References

### Login
POST https://api.example.com/login
Content-Type: application/json

{"username": "admin", "password": "secret"}

### Get Profile
GET https://api.example.com/profile
Authorization: Bearer {{Login.response.body.token}}

Prompt Variables (<<)

Interactive prompts resolved at request time. Placed in the request block (between ### and the request line). Resolved to block-level @var definitions.

### Create User
<<username
<<method [GET, POST, PUT, DELETE]
<<format [json|JSON, xml|XML, plain|Plain Text]
POST https://api.example.com/users

Pre-Request Scripts

< {% code %}

Multi-line:

< {%
  request.variables.set("key", "value")
  client.log("processing")
%}

External file:

< ./scripts/preprocess.lua

Post-Request Assertions

> {% code %}

Multi-line:

> {%
  client.test("Status is 200", function()
    client.assert(response.status == 200, "Expected 200")
  end)
%}

Cross-File References

import ./shared-vars.http
import ./auth.http as auth
run #Login
run #auth.GetToken (@env=staging)

Environment Override

### Staging Request
@env = staging
GET https://staging.example.com/api

Complete Example

# File-level variables
@base_url = https://api.example.com
@api_version = v2

import ./common/headers.http as headers

### Login
# Prompt for credentials
<<username
<<password
# Block-level override
@base_url = https://auth.example.com
POST {{base_url}}/oauth/token
Content-Type: application/json
< {%
  request.variables.set("req_id", md5.sum("login-" .. os.time()))
%}

{
  "username": "{{username}}",
  "password": "{{password}}",
  "grant_type": "password"
}

> {%
  client.test("Login successful", function()
    client.assert(response.status == 200, "Expected 200, got " .. response.status)
  end)
  client.test("Has token", function()
    client.assert(response.body.access_token ~= nil, "Missing access_token")
  end)
%}

### Get Users
GET {{base_url}}/{{api_version}}/users
Authorization: Bearer {{Login.response.body.access_token}}
X-Request-Id: {{$uuid}}