
# HTTP Client

The HTTP Client extension brings IntelliJ IDEA's HTTP Client to Zed. You write requests in `.http` or `.rest` files and run them with the ▶ button in the gutter; the response appears in Zed's terminal. In your code, every route or HTTP client call gets a lens that turns it into a ready request.

The file format is compatible with IntelliJ IDEA, WebStorm and PhpStorm, and largely with VS Code's REST Client, so existing `.http` files and `http-client.env.json` files work unchanged.

| | |
|---|---|
| Extension id | `http-client` |
| Version | `0.3.1` |
| Languages | HTTP (`.http`, `.rest`), plus request generation in Dart, Java, Kotlin, JavaScript, TypeScript, TSX, Python, Go, Rust, PHP, Ruby and C# |
| Runner | `zed-http`, a native binary the extension installs itself |
| Platforms | macOS and Linux; Windows should work but is untested |
| Source | [http-client-extension](https://github.com/farum-azula/zed_editor_extensions/tree/main/http-client-extension) in the zed_editor_extensions repository |

## What it gives

- **The HTTP language** for `.http` and `.rest` files: highlighting of methods, URLs, headers, `{{...}}` variables, HTTP versions and `###` separators; JSON, XML and GraphQL highlighting in the body; the file's requests in the outline panel (`Cmd-Shift-O`); `#` and `//` comments (`Cmd-/`).
- **A ▶ run button** in the gutter of every request, and tasks to run one or all requests.
- **Variables and environments**: file variables, `http-client.env.json` with a private file, `$shared`, and dynamic variables such as `{{$uuid}}`.
- **An environment switcher** above the first line of the file, and one per request.
- **Go to definition and hover** for every `{{variable}}`.
- **Request chaining**: named requests and references to the body, headers and status of earlier responses.
- **Bodies from files**, multipart, saving responses to files, Basic authorization shorthand, no-redirect.
- **Generating requests from code** in 50 frameworks and HTTP clients across 10 languages.
- **The `zed-http` command line tool**, for scripts, CI and AI agents.

## How it looks

Create `api.http`:

```http
@baseUrl = https://httpbin.org

### Get data
GET {{baseUrl}}/get?client=zed
Accept: application/json

### Create a record
POST {{baseUrl}}/post
Content-Type: application/json

{
  "id": "{{$uuid}}",
  "name": "Zed"
}
```

A ▶ appears in the gutter next to each `GET` and `POST` line. Clicking the one next to `GET` opens a terminal tab named `HTTP: GET {{baseUrl}}/get?client=zed` that shows:

```text
GET https://httpbin.org/get?client=zed
Accept: application/json

HTTP/1.1 200 OK  413 ms · 250 B
access-control-allow-origin: *
content-length: 250
content-type: application/json
date: Sat, 07 Nov 2026 19:05:38 GMT

{
  "args": {
    "client": "zed"
  },
  "headers": {
    "Accept": "application/json",
    "Host": "httpbin.org"
  },
  "method": "GET",
  "url": "https://httpbin.org/get?client=zed"
}

saved: ./.zed-http/line-3.json
```

When an environment file is found, an `environment: dev` line comes first.

The status is green for 2xx, yellow for 3xx and red for 4xx and 5xx. JSON is pretty-printed; binary bodies show only their size and type. The `saved:` path is clickable and opens the response in Zed with highlighting and search.

Hovering `{{baseUrl}}` shows its resolved value and where it comes from:

```text
baseUrl · environment `dev`
https://httpbin.org
```

Above the first line of the file, a row of lenses shows the environments, the file's own first:

```text
env: prod | dev | staging
```

## Running requests

| How | What runs |
|---|---|
| ▶ in the gutter next to the method | This request |
| `task: spawn` → `HTTP: GET …` | The request under the cursor, named after its `# @name` if it has one |
| `task: spawn` → `HTTP: run all requests in …` | All requests in the file, in order |
| `task: rerun` | The last run again |
| A key binding (see [Key bindings](#key-bindings)) | The request nearest the cursor |

The task and its terminal tab are named after the request's `# @name` (`HTTP: get-todos-by-id`), or after its method and URL.

## The .http file format

```http
### Optional title
# @name requestName
METHOD URL [HTTP/version]
Header: value
Header: value

request body
```

- Requests are separated by a line starting with `###`. Text after `###` is the title.
- The method is optional: a line with only `https://example.com` means `GET`. Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, `TRACE`, `CONNECT`.
- A URL without a scheme gets `http://`. A version at the end of the line is allowed and ignored.
- Headers follow the request line; the body comes after an empty line.
- Indented lines after the URL continue it, joined without spaces (`?q=zed` then `&limit=10`).
- `#` and `//` start comments.

### Directives

| Directive | Meaning |
|---|---|
| `# @name login` | The request's name: for `--name`, response references and the task title |
| `# @env prod` | The environment: of the whole file above the first `###`, of one request below it |
| `# @no-redirect` | Do not follow 3xx redirects |
| `# @no-log` | Do not save the response; later runs cannot reference it. Generated requests have it |

## Variables

Variables are written `{{name}}` in the URL, headers, body and file paths. Spaces inside the braces are allowed, and values can contain other variables.

```http
@host = api.example.com
@baseUrl = https://{{host}}/v1

GET {{baseUrl}}/users
```

File variables apply to the whole file and override environment values.

### Dynamic variables

| Variable | Result |
|---|---|
| `{{$uuid}}`, `{{$random.uuid}}` | A UUID v4 |
| `{{$timestamp}}` | Unix time in seconds |
| `{{$isoTimestamp}}` | UTC time in ISO 8601, such as `2026-10-16T11:01:53.123Z` |
| `{{$randomInt}}` | An integer from 0 to 999 |
| `{{$randomInt 1 100}}`, `{{$random.integer 1 100}}` | An integer in `[1, 100)` |
| `{{$random.float}}` | A float between 0 and 1 |
| `{{$random.alphabetic 8}}` | 8 random letters |
| `{{$random.alphanumeric 12}}` | 12 random letters and digits |
| `{{$random.hexadecimal 16}}` | 16 hex characters |
| `{{$processEnv.TOKEN}}`, `{{$env.TOKEN}}` | The OS environment variable `TOKEN` |

Each use generates a new value. Variables are looked up in this order: dynamic variables, file variables, the selected environment (private file over public), the `$shared` block, then references to stored responses. An unknown variable is an error, and the request is not sent.

## Environments

`http-client.env.json` is committed with the project:

```json
{
  "$shared": { "apiVersion": "v1" },
  "dev": { "baseUrl": "http://localhost:8080" },
  "prod": { "baseUrl": "https://api.example.com" }
}
```

`http-client.private.env.json` holds secrets and belongs in `.gitignore`:

```json
{
  "dev": { "token": "dev-secret" },
  "prod": { "token": "prod-secret" }
}
```

The private file is merged over the public one. The files are searched in the `.http` file's folder and its `.zed/http/`, then up the tree until the first match.

**Choosing an environment.** Click one in the lens row above the first line, which writes `# @env` into the file. A request can have an environment of its own: put the cursor on it, press `Cmd-.` and choose **HTTP: choose an environment for this request**. Its lens row then offers `from file` to remove it again. Lenses need `"code_lens": "on"` in Zed's settings; without them, type the `# @env` lines.

The environment is chosen by priority:

1. the `--env prod` flag of the CLI;
2. the request's own `# @env`, below its `###`;
3. the file's `# @env`, above the first `###`;
4. the `HTTP_CLIENT_ENV` variable, for example in `"terminal": { "env": { "HTTP_CLIENT_ENV": "prod" } }`;
5. `dev`, `local` or `development`, if present;
6. the first environment in the file.

An environment that is not defined stops the run before anything is sent, and is marked `(not defined)` in the lens.

## Go to definition

`Cmd`-click or `F12` on a variable:

| Under the cursor | Goes to |
|---|---|
| `{{token}}` declared with `@token = ...` | The `@token` line |
| `{{baseUrl}}` from an environment | The `"baseUrl"` key in `http-client.env.json` or the private file |
| `{{login.response.body.token}}` | `# @name login` |
| `{{$uuid}}` and other dynamic variables | Nowhere |

When a variable is in both the public and private files, Zed lists both. The hover of a response reference shows the stored value, or says the request has not run yet; the hover of a dynamic variable shows a sample value.

## Request chaining

Responses of named requests are stored and can be used in later requests:

```http
### Login
# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{ "user": "admin", "password": "{{password}}" }

### Profile
GET {{baseUrl}}/me
Authorization: Bearer {{login.response.body.accessToken}}
```

| Expression | Value |
|---|---|
| `{{login.response.body}}` | The whole body |
| `{{login.response.body.data.token}}` | A JSON field by path |
| `{{login.response.body.$.data.token}}` | The same, JSONPath style |
| `{{login.response.body.items[0].id}}` | An array element |
| `{{login.response.headers.Location}}` | A header, case-insensitive |
| `{{login.response.status}}` | The status code |

Responses are stored in `.zed-http/responses.json` next to the `.http` file and survive restarts: run `login` once, and the other requests can then be run one by one. Requests without `@name` are stored as `line-<number>`.

## Bodies and responses

| Syntax | Effect |
|---|---|
| A body after the empty line | Sent as is, up to the next `###`; trailing empty lines are trimmed |
| `< ./payloads/item.json` as the body | The file is sent as bytes, without variable substitution |
| `< ./report.txt` inside a multipart body | Replaced with the file's text |
| `Authorization: Basic user password` | Base64-encoded automatically (`user:password` too) |
| `>> ./out/report.csv` after the request | Saves the response; `report-1.csv`, `report-2.csv`, ... if it exists |
| `>>! ./out/report.csv` | Saves the response, overwriting the file |

Every response is also saved to `.zed-http/<name or line-N>.<ext>`, with the extension chosen by `Content-Type`. Add to `.gitignore`:

```text
.zed-http/
http-client.private.env.json
```

## Generating a request from code

Every route or HTTP client call in your code gets a **🌐 Generate .http request** lens above the line. One click appends a full request to `.zed/http/endpoints/<source file>.http` (`server.ts` becomes `server.ts.http`) and opens it. Once a request exists, the lens becomes **🔗 Open** followed by the file name, such as `🔗 Open server.ts.http`. The same actions are in the `Cmd-.` menu. Code lenses are off by default in Zed; turn them on:

```json
{ "code_lens": "on" }
```

With `"menu"`, the lenses appear in the `Cmd-.` menu instead. A gutter ▶ is not possible here: an extension can add gutter buttons only to languages it defines itself.

The request is filled in from the handler and the model classes in the same file: path variables become `{{id}}` with `@id = 1` at the top; query parameters, headers and a JSON body with type-based placeholders (`""`, `0`, `false`, `[]`, nested objects) are added; and `Authorization: Bearer {{token}}` is added when the handler requires authentication. For a Spring for Dart controller:

```dart
@RestController()
@RequestMapping('/api/books')
class BookController {
  @GetMapping('/{isbn}')
  Future<Book> find(@PathVariable() String isbn) => books.find(isbn);

  @PostMapping()
  Future<ResponseEntity<Book>> create(
    @RequestHeader('X-Request-Id') String requestId,
    @RequestBody() @Valid() NewBook book,
  ) async => ...
}

class NewBook {
  const NewBook({required this.isbn, required this.title, this.stock = 0});

  final String isbn;
  final String title;
  final int stock;
}
```

the lenses on `@GetMapping` and `@PostMapping` append to `.zed/http/endpoints/book_controller.dart.http`:

```http
### get-api-books-by-isbn
# @name get-api-books-by-isbn
# @no-log
@isbn = 1
GET {{baseUrl}}/api/books/{{isbn}}
Accept: application/json

### post-api-books
# @name post-api-books
# @no-log
@xRequestId = value
POST {{baseUrl}}/api/books
Accept: application/json
X-Request-Id: {{xRequestId}}
Content-Type: application/json

{
  "isbn": "",
  "title": "",
  "stock": 0
}
```

**The server's address.** For a Spring application, Spring Boot in Java or Kotlin or Spring for Dart, the extension reads `server.port`, `server.servlet.context-path`, `server.address` and TLS settings from `application.yml`, `application.yaml` or `application.properties` (in `lib/resources/` for Spring for Dart). The first generated request creates `.zed/http/http-client.env.json` with that address, such as `"baseUrl": "http://localhost:9090/shop"`. A `baseUrl` you set yourself is never changed.

**Clients go where the client goes.** A Feign client (`@FeignClient`, Java and Dart) uses its `url`, with `${...}` placeholders resolved from the same configuration. What cannot be resolved becomes a variable named after the property, such as `{{catalogUrl}}`.

**URLs kept in a variable**, as in `http.post(_endpoint, ...)`, are found too: the request uses the URL assigned to the variable, the environment variable it is read from (`{{GROQ_URL}}`), or the variable's name when it names a URL (`{{apiUrl}}`).

A URL assembled across several statements or files is not found, and models defined in other files are not resolved; the body is then `{}`.

### Supported frameworks

A framework is active in a file only when the file has one of its imports, so frameworks of the same language do not interfere.

| Language | Frameworks and clients |
|---|---|
| Dart and Flutter | Spring Web for Dart (`spring_boot_starter_web`), Feign for Dart (`spring_boot_starter_feign`), Dio, `package:http`, retrofit.dart, Chopper, shelf_router |
| Java | Spring Web (MVC, WebFlux, OpenFeign), JAX-RS (Quarkus, Jakarta EE, Helidon, Dropwizard), Micronaut, Retrofit, OpenFeign |
| Kotlin | Spring Web, Ktor server, Ktor client, Retrofit, JAX-RS (Quarkus) |
| TypeScript and JavaScript | Express, Fastify, Hono, Koa router, NestJS, Axios, Angular HttpClient, fetch |
| Python | FastAPI, Flask, Django URLconf, requests / httpx / aiohttp |
| Go | gorilla/mux, net/http, Gin, Echo, chi, Fiber |
| Rust | axum, actix-web, Rocket, reqwest |
| PHP | Laravel, Symfony, Slim, Guzzle |
| Ruby | Rails routes, Sinatra, Faraday / HTTParty |
| C# | ASP.NET Core controllers, ASP.NET Core minimal APIs, Refit, HttpClient |

The catalog is [frameworks.json](https://github.com/farum-azula/zed_editor_extensions/blob/main/http-client-extension/frameworks.json): patterns written as source code with typed placeholders, not regular expressions. A project can add its own frameworks in `.zed/http/frameworks.json`, which is merged into the built-in catalog and picked up on save:

```json
{
  "$schema": "https://raw.githubusercontent.com/farum-azula/zed_editor_extensions/main/http-client-extension/frameworks.schema.json",
  "languages": {
    "dart": {
      "frameworks": {
        "my-api-client": {
          "name": "Our ApiClient",
          "imports": ["package:my_app/api_client.dart"],
          "routes": ["api.call(\"{method}\", \"{route}\""],
          "body": ["api.call(...data: {keys}"]
        }
      }
    }
  }
}
```

`zed-http frameworks` in the project root checks the merged catalog and prints it. The [examples/code](https://github.com/farum-azula/zed_editor_extensions/tree/main/http-client-extension/examples/code) folder has one runnable file per framework.

## New endpoint

The `http: new endpoint` task asks in the terminal for the method, URL and name, creates `.zed/http/endpoints/<name>.http` and opens it (when the `zed` command is on the `PATH`). It also creates `.zed/http/http-client.env.json` with a `dev` profile if there are no environments yet. Extension tasks are visible only while a `.http` file is open; to have this one everywhere, add it to `~/.config/zed/tasks.json`:

```json
[
  {
    "label": "http: new endpoint",
    "command": "zed-http",
    "args": ["new", "\"$ZED_WORKTREE_ROOT\""],
    "use_new_terminal": true,
    "reveal": "always",
    "hide": "on_success"
  }
]
```

## The zed-http command

The runner works on its own, in a terminal, in scripts and in CI:

```text
zed-http run <file.http> [--line N | --name NAME | --all] [--env ENV] [--raw] [--timeout SECS]
zed-http list <file.http>
zed-http envs <file.http>
zed-http new [ROOT] [--name NAME] [--method METHOD] [--url URL] [--from FILE:LINE] [--no-open]
zed-http detect <file> [--line N]
zed-http frameworks [ROOT]
zed-http lsp
```

| Command or flag | Does |
|---|---|
| `run` | Runs requests |
| `list` | Lists requests: line, method, URL, name |
| `envs` | Lists the environments |
| `new` | Creates `ROOT/.zed/http/endpoints/<name>.http`; `--from FILE:LINE` takes the method and URL from code; `--no-open` does not open it |
| `detect` | Finds endpoints in code: line, method, URL and framework, tab-separated |
| `frameworks` | Prints the supported frameworks and checks `ROOT/.zed/http/frameworks.json` |
| `lsp` | The language server, started by Zed |
| `-l`, `--line N` | The request containing line `N` |
| `-n`, `--name NAME` | The request by `@name` or title |
| `-a`, `--all` | All requests, in order |
| `-e`, `--env ENV` | The environment |
| `--raw` | No JSON formatting |
| `--timeout SECS` | The request timeout; 60 seconds by default |

The exit code is `0` when every request returned a status below 400, `1` when one returned 4xx or 5xx or failed, and `2` for an argument, file, variable or environment error. So `zed-http run smoke.http --all --env staging` works as a CI check.

```sh
$ zed-http detect lib/api/auth_api.dart
12	POST	{{baseUrl}}/auth/login	dart/dio
```

## Key bindings

To run the request under the cursor with `Cmd-Enter`, keeping focus in the editor, add to your keymap (`zed: open keymap`):

```json
[
  {
    "context": "Editor && extension == http",
    "bindings": {
      "cmd-enter": ["editor::SpawnNearestTask", { "reveal": "no_focus" }]
    }
  }
]
```

## How the runner is installed

The extension finds `zed-http` in this order:

1. a `zed-http` already on the `PATH`; your own installation always wins;
2. a copy it installed earlier, in its folder under Zed's extension work directory;
3. the release build for this platform, downloaded from the repository's [releases](https://github.com/farum-azula/zed_editor_extensions/releases) (macOS and Linux, Intel and ARM);
4. a build from the extension's own `cli/` folder with `cargo install`, the usual case for a dev extension cloned from the repository. The first start then takes as long as a release build of the runner.

Zed shows the server as installing meanwhile. The server keeps a copy of itself in `~/.zed-http/bin`, where the ▶ button looks when the `PATH` has no `zed-http`. To install the runner by hand, for use as a CLI:

```sh
cd zed_editor_extensions/http-client-extension
cargo install --path cli
```

## Limitations

- JavaScript response handlers (`> {% ... %}`) and pre-request scripts are skipped; use `{{name.response...}}` to pass data between requests.
- The response is shown in the terminal, not in a panel of its own: a Zed extension cannot add panels.
- No WebSocket, gRPC, GraphQL subscriptions or HTTP/2-specific features. Send GraphQL queries as a `POST` with JSON.
- No cookie jar between requests.
- `$processEnv` values come from the Zed terminal's environment.

## Troubleshooting

**No ▶ in the gutter.** Check that the language in the bottom right is **HTTP**, and that `"gutter": { "runnables": true }` is not turned off. If the ▶ is there but running reports `zed-http: command not found`, the server has not started yet in this window: open a `.http` file, wait for **zed-http** in the status bar, and run again.

**The ▶ is there, but no `HTTP: …` task is offered.** Copy the extension's `languages/http/tasks.json` to the project's `.zed/tasks.json`.

**`Cmd`-click on a variable does nothing.** Run `editor: restart language server` and check `dev: open language server logs`.

**`zed-http: command not found` with a runner you installed with cargo.** `~/.cargo/bin` is not on the `PATH` of the shell Zed starts. Add it to your shell profile and restart Zed.

**`unknown variable {{baseUrl}}`.** `http-client.env.json` was not found, or the environment lacks the variable. Run `zed-http envs file.http` and check the `environment:` line at the start of the output.

**`no stored response for request 'login'`.** Run the request with `# @name login` first.

**TLS errors with a self-signed certificate.** The system's root certificates are used; add your CA to the system store.

## Links

- [Source of the extension](https://github.com/farum-azula/zed_editor_extensions/tree/main/http-client-extension)
- [Example requests](https://github.com/farum-azula/zed_editor_extensions/blob/main/http-client-extension/examples/requests.http)
- [Releases with the runner binaries](https://github.com/farum-azula/zed_editor_extensions/releases)
- [Installation](installation.md)
