# Exploring the HTTP request syntax

This section describes the HTTP request format. For more information about sending HTTP requests and viewing HTTP responses, refer to [HTTP Client](http-client-in-product-code-editor.html).

To compose an HTTP request in the IntelliJ IDEA code editor, use the following general syntax:

```HTTP_REQUEST_FULL
Method Request-URI HTTP-Version
Header-field: Header-value

Request-Body
```

Procedure: Use comments in HTTP requests

* Within a request, start any line with `//` or `#` to make it a comment line.

```HTTP_REQUEST_FULL
// A basic request
GET http://example.com/a/
```

Procedure: Set names for HTTP requests

To quickly find your request in [run/debug configurations](http-client-in-product-code-editor.html#http-request-run-debug-configurations), [Search Everywhere](searching-everywhere.html), and [Run Anything](running-anything.html#send_http_requests), you can give it a name.

* Type a name above the request next to `###`, `# @name`, or `# @name =`.

![Enter the HTTP request name](https://resources.jetbrains.com.cn/help/img/idea/2026.2/aqua_http_request_name.png)

If a request does not have a name, IntelliJ IDEA will use its position in the request file (such as `#1`) as the request name. If a request file contains multiple requests with the same name, IntelliJ IDEA will append the request position number to each of the names. This will make each request name unique so that you can easily find the needed one in the Services tool window, run/debug configurations, and so on.

![HTTP requests in Services tool window](https://resources.jetbrains.com.cn/help/img/idea/2026.2/aqua_http_request_same_names.png)

Procedure: Use short form for GET requests

* For GET requests, you can omit the request method and only specify the URI.

```HTTP_REQUEST_FULL
// A basic request
https://example.com/a/
```

In the Java context, you can use [code completion](auto-completing-code.html) `Ctrl+Space` (Windows), `⌃ Space` (macOS), `⌃ Space` (IntelliJ IDEA Classic (macOS)), `⌃ Space` (macOS System Shortcuts), `Ctrl+Space` (XWin), `Ctrl+Space` (GNOME), `Ctrl+Space` (KDE), `Alt+/` (Emacs), `Ctrl+Space` (Sublime Text), `⌃ Space` (Sublime Text (macOS)), `Ctrl+Space` (NetBeans), `Ctrl+Space` (Visual Studio), `⌃ Space` (Visual Studio (macOS)), `Ctrl+Space` (Eclipse), `⌃ Space` (Eclipse (macOS)) to specify URIs based on the defined `@Path` annotations. Any changes to the `@Path` annotations in Java code will be reflected in the contents of the suggestion list.

Procedure: Compose several requests in a single file

1. Mark the end of a request by typing the `###` separator below it.

```HTTP_REQUEST_FULL
// A basic request
https://example.com/a/

###
```

2. Compose another request below the separator.

```HTTP_REQUEST_FULL
// A basic request
https://example.com/a/

###

// A second request using the GET method
https://example.com:8080/api/html/get?id=123&value=content
```

Procedure: Set an execution delay

* The `sleep(ms)` function allows you to pause the execution of an HTTP request or a script for a specified duration in milliseconds. This is particularly useful for various connection tests, websocket testing, and more.

Use the `sleep()` function together with the `await` keyword to pause execution: `await sleep(milliseconds)`.

* If you want to schedule a piece of code to run after a delay without blocking the rest of the script, use the [Web API methods](https://developer.mozilla.org/en-US/docs/Web/API/Window):

* [setTimeout()](https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout): schedules a function to run once after the specified number of milliseconds. Returns a timer ID.

* [clearTimeout()](https://developer.mozilla.org/en-US/docs/Web/API/Window/clearTimeout): cancels a timeout set with `setTimeout()`. Accepts a timer ID.

* In pre-request scripts, you can delay the actual sending of an HTTP request. In response handlers, use the functions to delay test execution or logic following a received response.

```HTTP_REQUEST_FULL
< {%
    const job = setTimeout(() => {
        console.log("This timer is cleared and will not execute.");
    }, 1000);

    console.log("Pre-request: Starting sleep...");
    clearTimeout(job);

    const start = Date.now();
    await sleep(10000);

    console.log(`Pre-request: Finished sleep after ${Date.now() - start}ms`);
    console.log("Pre-request: Proceeding to request.");
%}

GET https://examples.http-client.intellij.net/anything

> {%
    setTimeout(() => {
        console.log("Post-script: One second timer fired during sleep.");
    }, 1000);

    console.log("Post-script: Starting sleep...");

    const start = Date.now();
    await sleep(10000);

    console.log(`Post-script: Finished sleep after ${Date.now() - start}ms`);
    console.log("Post-script: Script execution complete.");
%}
```

Procedure: Break long requests into several lines

* Indent all query string lines but the first one.

```HTTP_REQUEST_FULL
// Using line breaks with indent
GET http://example.com:8080
    /api
    /html
    /get
    ?id=123
    &value=content
```

> **Tip:**
> The indent size for the URL parts is configured in `Settings | Editor | Code Style | HTTP Request | Tabs and Indents | URL parts indent`.

* If the URL is too long because of the query string, you can use the dedicated context action to put each query parameter on a new line. Place the caret at the query string part, press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (NetBeans), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)) (Show Context Actions), and select Put query parameters on separate lines.

Before:

```HTTP_REQUEST_FULL
GET https://example.com:8080/api/get/html?firstname=John&lastname=Doe&planet=Tatooine&town=Freetown
```

After:

```HTTP_REQUEST_FULL
GET https://example.com:8080/api/get/html?
    firstname=John&
    lastname=Doe&
    planet=Tatooine&
    town=Freetown
```

> **Note:**
> You can enforce the consistent wrapping of query parameters using the HTTP Client code style in `Settings | Editor | Code Style | HTTP Request | Wrapping and Braces | Query parameters wrap`.

* Similarly, you can format the body in requests with `Content-Type: application/x-www-form-urlencoded`. Place the caret at the body, press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (NetBeans), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)) (Show Context Actions), and select  Put form-urlencoded parameters on separate lines .

Before:

```HTTP_REQUEST_FULL
POST https://ijhttp-examples.jetbrains.com/post
Content-Type: application/x-www-form-urlencoded

key1=value1&key2=value2&key3=value3&key4=value4&key5=value5
```

After:

```HTTP_REQUEST_FULL
POST https://ijhttp-examples.jetbrains.com/post
Content-Type: application/x-www-form-urlencoded

key1 = value1 &
key2 = value2 &
key3 = value3 &
key4 = value4 &
key5 = value5
```

To configure wrapping for the `x-www-form-urlencoded` body, use `Settings | Editor | Code Style | HTTP Request | Wrapping and Braces | Form-urlencoded parameters wrap`. To configure spaces before and after `=` and before `&`, use `Settings | Editor | Code Style | HTTP Request | Spaces`.

Procedure: Access a web service with authentication

* Depending on the web service you are accessing, provide the [basic](https://en.wikipedia.org/wiki/Basic_access_authentication) or [digest](https://en.wikipedia.org/wiki/Digest_access_authentication) Authorization header.

```HTTP_REQUEST_FULL
// Basic authentication
GET http://example.com
Authorization: Basic username password

###

// Digest authentication
GET http://example.com
Authorization: Digest username password
```

> **Note:**
> Similarly to other HTTP request elements, the provided `username` and `password` can be parameterized by means of [environment variables](http-client-variables.html).

Procedure: Provide the request message body

Inside the request, prepend the request body with a blank line and do one of the following:

* Type the request body in place:

```HTTP_REQUEST_FULL
// The request body is provided in place
POST https://example.com:8080/api/html/post HTTP/1.1
Content-Type: application/json
Cookie: key=first-value

{ "key" : "value", "list": [1, 2, 3] }
```

If you set the Content-Type header field value to one of the  [supported languages](discover-intellij-idea.html#IntelliJ-IDEA-supported-languages), then the corresponding language fragment will be [auto-injected](using-language-injections.html) into the HTTP request message body. If Content-Type is not specified, you can inject a language fragment manually.

* In the Java context, you can use  [code completion](auto-completing-code.html)   `Ctrl+Space` (Windows), `⌃ Space` (macOS), `⌃ Space` (IntelliJ IDEA Classic (macOS)), `⌃ Space` (macOS System Shortcuts), `Ctrl+Space` (XWin), `Ctrl+Space` (GNOME), `Ctrl+Space` (KDE), `Alt+/` (Emacs), `Ctrl+Space` (Sublime Text), `⌃ Space` (Sublime Text (macOS)), `Ctrl+Space` (NetBeans), `Ctrl+Space` (Visual Studio), `⌃ Space` (Visual Studio (macOS)), `Ctrl+Space` (Eclipse), `⌃ Space` (Eclipse (macOS)) to specify the `Accept` header field value based on the defined `@Produces` annotations. Any changes to the `@Produces` annotations in Java code will be reflected in the contents of the suggestion list.

* To read the request body from a file, type the `<` symbol followed by the path to the file.

```GENERIC
// The request body is read from a file
POST https://example.com:8080/api/html/post
Content-Type: application/json

< ./input.json
```

Procedure: Use multipart/form-data content type

* Set the request's Content-Type to multipart/form-data. To send a file as part of the multipart/form-data message, include the `filename` parameter in the Content-Disposition header.

```HTTP_REQUEST_FULL
POST https://example.com/api/upload HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="first"; filename="input.txt"

// The 'input.txt' file will be uploaded
< ./input.txt

--boundary
Content-Disposition: form-data; name="second"; filename="input-second.txt"

// A temporary 'input-second.txt' file with the 'Text' content will be created and uploaded
Text
--boundary
Content-Disposition: form-data; name="third";

// The 'input.txt' file contents will be sent as plain text.
< ./input.txt --boundary--
```

> **Tip:**
> To speed up creating a multipart/form-data request, use the mptr [live template](using-live-templates.html).

Procedure: Disable following redirects

When an HTTP request is redirected (a 3xx status code is received), the redirected page response is returned. In the Services tool window, you can view the redirected page response as well as all redirections that happened during the request.

You may want to disable following redirects. In this case, the actual redirect response header (such as 301 or 302) is returned.

* Before the request, add a comment line with the `@no-redirect` tag.

```HTTP_REQUEST_FULL
// @no-redirect
example.com/status/301
```

If you already have a redirected request, you can click Disable next to the `Redirections` list in the Services tool window. This will add the `@no-redirect` tag to the initial request.

![HTTP response with redirections](https://resources.jetbrains.com.cn/help/img/idea/2026.2/aqua_http_response_redirect.png)

Procedure: Disable saving requests to requests history

If necessary, you can prevent saving a request to the [requests history](http-client-in-product-code-editor.html#requests_history). This can be helpful in case a request contains some sensitive data, and you don't want to log it.

* Before the request, add a comment line with the `@no-log` tag.

```HTTP_REQUEST_FULL
// @no-log
GET example.com/api
```

Procedure: Disable saving received cookies to the cookies jar

If necessary, you can prevent saving the received cookie [to the cookies jar](http-client-in-product-code-editor.html#manage_cookies). This way you will avoid removing the unwanted cookies from the  `http-client.cookies` file manually.

* Before the request, add a comment line with the `@no-cookie-jar` tag.

```HTTP_REQUEST_FULL
// @no-cookie-jar
GET example.com/api
```

Procedure: Disable encoding

By default, the HTTP client encodes the request parameters and body into an ASCII format. For example, a slash character in your request parameter will be sent as `%2F`. You can disable encoding to send the request as it is.

* Before the request, add a comment line with the `@no-auto-encoding` tag.

Encoding disabled:

When the tag is used, the request parameters and body are not encoded:

```HTTP_REQUEST_FULL
# @no-auto-encoding
GET https://examples.com/api?
            name=@#$somebody&
            qwerty=%40%23%24
```

The resulting request will be sent unchanged:

```HTTP_REQUEST_FULL
https://examples.com/api?name=@#$somebody&qwerty=%40%23%24
```

Encoding enabled:

Encoding is enabled by default when the tag is not used.

```HTTP_REQUEST_FULL
### Default behavior
GET https://examples.com/api?
            name=@#$somebody&
            qwerty=%40%23%24
```

In this request, parameters will be encoded:

```HTTP_REQUEST_FULL
https://examples.com/api?name=%40%23%24somebody&qwerty=%40%23%24
```

Procedure: Customize HTTP request timeouts

The HTTP Client has a timeout of 60 seconds for establishing a connection with a server, and a separate 60 seconds timeout for awaiting new packets in ongoing connections. You can customize both of these timeouts.

* To set a timeout for new packets in established connections, add a comment line with the `@timeout` tag before the request.

```HTTP_REQUEST_FULL
# @timeout 600
GET example.com/api
```

* To set a connection timeout, add a comment line with the `@connection-timeout` tag before the request.

```HTTP_REQUEST_FULL
// @connection-timeout 2 m
GET example.com/api
```

By default, the timeout values are in seconds, but you can add an explicit unit of time after the value: `ms` for milliseconds, `s` for seconds, `m` for minutes, for example `100 ms` or `5 m`.

> **Note:**
> You can also change these timeouts at the IDE level, using VM options (`Help | Edit Custom VM Options`).
>
>
>
> * `-Didea.connection.timeout` configures connection timeout (in milliseconds by default). In individual HTTP requests, the `@connection-timeout` attribute overrides it.
>
> * `-Didea.read.timeout` configures timeout for new packets (in milliseconds by default). In individual HTTP requests, the `@timeout` attribute overrides it.
>
>
>
> Be aware that VM options impact IntelliJ IDEA behavior across the entire application. These timeouts apply not just to HTTP requests made using the HTTP Client, but also to all HTTP requests that IntelliJ IDEA might send when interacting with the network, such as when accessing an external service.

## Handle the response

You can handle the response using JavaScript. Type the `>` character after the request and specify the path and name of the JavaScript file or put the response handler script code wrapped in `{% ... %}`.

```HTTP_REQUEST_FULL
GET https://httpbin.org/get

> /path/to/responseHandler.js
```

```HTTP_REQUEST_FULL
GET https://httpbin.org/get

> {%
    client.global.set("my_cookie", response.headers.valuesOf("Set-Cookie")[0]);
%}
```

For more information, refer to [HTTP Response handling API reference](http-response-handling-api-reference.html).

## Redirect the response

You can redirect a response to a file. Use `>>` to create a new file with a suffix if it already exists and `>>!` to rewrite the file if it exists. You can specify an absolute path or relative to the current HTTP Request file. You can also use variables in paths, including environment variables and the following predefined variables:

* `{{$projectRoot}}` points to the project root directory

* `{{$historyFolder}}` points to `.idea/httpRequests/`

The following example HTTP request creates `myFile.json` in `myFolder` next to the HTTP Request file and redirects the response to it. If the file already exists, it creates `myFile-1.json`.

```HTTP_REQUEST
POST https://httpbin.org/post
Content-Type: application/json

{
  "id": 999,
  "value": "content"
}

>> myFolder/myFile.json
```

The following example HTTP request creates `myFile.json` in `.idea/httpRequests/`. If the file already exists, it overwrites the file. It also [handles the response](#response-handling) with the `handler.js` script that resides in the project root.

```HTTP_REQUEST
POST https://httpbin.org/post
Content-Type: application/json

{
  "id": 999,
  "value": "content"
}

> {{$projectRoot}}/handler.js

>>! {{$historyFolder}}/myFile.json
```

> **Note:**
> For Windows, specify paths with the backslash `\`.