Skip to main content
HTTPSpec uses the standard .http file format for defining HTTP requests. This page covers the complete syntax for request lines, headers, and bodies.

​
Request Line

The request line is the first line of each request block and follows this format: 
<HTTP_METHOD> <URL> [HTTP_VERSION]

​
Components

  • HTTP Method (required) - Standard HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
  • URL (required) - Complete URL including protocol (http:// or https://)
  • HTTP Version (optional) - Defaults to HTTP/1.1 if not specified
GET https://api.example.com/users/123

​
Supported HTTP Versions

  • HTTP/1.0
  • HTTP/1.1 (default)
  • HTTP/2
  • HTTP/3

​
Headers

Headers are specified as Key: Value pairs on separate lines following the request line. Each header must be on its own line.
Request with Headers
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json
User-Agent: HTTPSpec/1.0
Authorization: Bearer abc123
Header names are case-insensitive per HTTP specification, but HTTPSpec preserves the casing you provide.

​
Common Headers

Specifies the media type of the request body:
POST https://api.example.com/users
Content-Type: application/json

{"name": "Alice"}
Used for authentication:
GET https://api.example.com/protected
Authorization: Bearer token123
Indicates expected response format:
GET https://api.example.com/data
Accept: application/json

​
Request Body

The request body starts after a blank line following the headers. Everything between the blank line and the assertions (or next request) is treated as the body.

​
JSON Body

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

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

//# status == 201

​
Plain Text Body

POST with Text
POST https://api.example.com/echo
Content-Type: text/plain

Hello, World!

//# status == 200

​
Multiline Body

Bodies can span multiple lines. HTTPSpec preserves line breaks in the body content:
Multiline JSON
POST https://api.example.com/posts
Content-Type: application/json

{
  "title": "My Post",
  "content": "This is a long post\nthat spans multiple lines",
  "tags": ["http", "testing"],
  "published": true
}

//# status == 201

​
Request Names

You can name your requests using a comment line starting with ###. This makes test output more readable and helps organize your test files.
Named Requests
### Get user by ID
GET https://api.example.com/users/123

//# status == 200

### Create new user
POST https://api.example.com/users
Content-Type: application/json

{"name": "Alice"}

//# status == 201
The name appears in test output and helps you identify which request failed if there are issues.

​
Multiple Requests in One File

You can include multiple request blocks in a single file. Requests are separated by blank lines or request names and executed sequentially.
Sequential Requests
### Make a 200 request
GET http://httpbin.org/status/200
Content-Type: application/json

### Make a 404 request
GET http://httpbin.org/status/404
Content-Type: application/json

//# status == 404
Requests are executed in order. If an early request fails, subsequent requests still execute unless the failure is critical.

​
Comments

Lines starting with # or // (but not //#) are treated as comments and ignored by the parser:
With Comments
# This is a test for the user API
// Another comment style

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

//# status == 200
The //# prefix is reserved for assertions and is not treated as a regular comment.

​
Real-World Example

Here’s a complete example from the HTTPSpec test suite:
test.httpspec
### Test JSONPlaceholder API
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json

//# status == 200
//# body contains "Leanne Graham"

### Test with some failing assertions (to show diagnostics)
GET https://httpbin.org/json

//# status == 404
//# body contains "nonexistent"
//# header["content-type"] == "text/plain"

​
Next Steps

Assertions

Learn how to validate responses with assertions

Variables

Use variables for dynamic request values

Build docs developers (and LLMs) love

Get started for freeTalk to us