What are .http files?

A .http file is a plain text file containing one or more HTTP requests, written in a syntax that closely mirrors the HTTP protocol itself. You write the method, URL, headers, and body — then your editor or CLI tool sends it.

Origins

The .http file format was created by Huachao Mao, a senior engineer at Alibaba Cloud. His REST Client extension for VS Code — first released on March 31, 2016 — introduced the idea of writing HTTP requests as plain text in your editor and running them directly. The concept was simple and immediately useful: no external tool, no GUI, just a text file that speaks HTTP.

The extension grew steadily from a basic request sender into a full-featured HTTP workbench. By late 2016, Mao had added the ### separator for multiple requests per file, establishing the syntax pattern that every subsequent implementation would adopt. Today the extension has over 7 million installs.

The format's appeal was evident enough that JetBrains independently adopted and significantly extended it for IntelliJ-based IDEs, adding scripting, response handlers, and protocol support. JetBrains also published the only semi-formal specification — though it remains incomplete and has not kept pace with any implementation, including their own.

httpyac, Visual Studio 2022, kulala.nvim, and many others followed. Each brought their own extensions, but the core idea — Mao's idea — remains: a plain text file that describes an HTTP request in a syntax anyone who knows HTTP can read.

Everything on this site builds on that foundation.

A simple example

GET https://httpbin.org/get
Accept: application/json

That's a complete .http file. Save it, open it in a supported editor, and you can execute the request directly.

Multiple requests in one file

Use ### to separate requests:

### Get users
GET https://api.example.com/users

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

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

### Delete user
DELETE https://api.example.com/users/42

Each request is independent and can be executed individually.

Beyond the basics

The core syntax is simple, but the format supports much more:

• Variables and environments for switching between dev/staging/prod (Section 4: Variables)
• Response chaining to pass data between requests (Section 4: Variables)
• Scripting and assertions for API testing (Section 12: Response Handlers)
• GraphQL, WebSocket, and gRPC support in some clients (Section 18: Protocols)

Not all features are supported by all clients. The compatibility reference tracks exactly what works where.

Why not Postman/Insomnia/curl?

.http files complement these tools rather than replacing them:

• vs. Postman/Insomnia: .http files are plain text, version-controllable, reviewable in PRs, and don't require a proprietary app or account.
• vs. curl: .http files are more readable for multi-step workflows, support variables and environments, and integrate directly into your editor.
• vs. OpenAPI/Swagger: .http files are for executing requests, not describing APIs. They're what you reach for when testing, debugging, or demonstrating.

The state of standardization

There is no RFC or formal standard for .http files. The format is a de facto standard that emerged from convergent implementation. This site aims to document the complete feature set across all implementations and serve as the neutral reference for the format going forward.

Three layers of compatibility exist:

Universal Supported identically by all major implementations.

Universal core — request syntax, ### separators, # and // comments, {{variables}}, @var = value definitions. Works identically everywhere.

Widely Supported Supported by 3+ implementations, possibly with syntax variations.

Widely supported — environments, file includes, metadata tags, auth helpers. Shared by most tools, sometimes with syntax variations.

Implementation-Specific Unique to a single implementation. Not portable.

Implementation-specific — scripting, assertions, protocol extensions, import/run. Not portable without targeting a specific client.