Exploring the HTTP request syntax

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

Request-Body

Use short form for GET requests

For GET requests, you can omit the request method and only specify the URI.
```
// A basic request
https://example.com/a/
```
In the Java context, you can use code completion CtrlSpace 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.

Compose several requests in a single file

Mark the end of a request by typing the ### separator below it.
```
// A basic request
https://example.com/a/

###
```

Compose another request below the separator.

// 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

Break long requests into several lines

Indent all query string lines but the first one.
```
// 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 AltEnter (Show Context Actions), and select Put query parameters on separate lines.
Before
GET https://example.com:8080/api/get/html?firstname=John&lastname=Doe&planet=Tatooine&town=Freetown
After
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 AltEnter (Show Context Actions), and select Put form-urlencoded parameters on separate lines.
Before
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
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.

Access a web service with authentication

Depending on the web service you are accessing, provide the basic or digest Authorization header.

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

###

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

Provide the request message body

Type the request body in place:
```
// 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, then the corresponding language fragment will be auto-injected 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 CtrlSpace 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.

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

< ./input.json

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.

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.

Disable following redirects

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.

Disable saving requests to requests history

Disable saving received cookies to the cookies jar

Disabling 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

Encoding enabled

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

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

The resulting request will be sent unchanged:

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

Customize HTTP request timeouts

To set a timeout for new packets in established connections, add a comment line with the @timeout tag before the request.
```
# @timeout 600
GET example.com/api
```
To set a connection timeout, add a comment line with the @connection-timeout tag before the request.
```
// @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.

Use variables

note
If you need to use curly braces in your request but don't want them to be treated as HTTP Client variables, use URL-encoded format: %7B for { and %7D for }. For example:
### send URL-encoded {{variable}}

GET https://www.example.com/search?q=%7B%7Bvariable%7D%7D

The variable's name may contain letters, digits, the underscore symbols _, the hyphen symbols -, or the dot symbol . (see the note below about dots in variable names).

tip
Starting with version 2024.2, IntelliJ IDEA treats all variables in HTTP requests (except for built-in dynamic variables) as JSONPath expressions. This helps you access collections in variable values. And it also means that if you use dots . in your variable name, the HTTP Client expects its value to match JSON data. For example, the value of the {{client.host.url}} can be represented in a dev environment file as:
{
  "dev":{
    "client": {
      "host": {
        "url": "example.org"
      }
    }
  }
}
# assuming an environment is selected, 'dev' in our case

GET {{client.host.url}}
If you want a variable name to contain dots, you should enclose it in quotes and square brackets when using in HTTP requests. For example:
{
  "dev":{
    "client": {
      "host.url": "example.org"
    }
  }
}
GET {{client.['host.url']}}
Refer to Iterate over collections in variables for more examples on using JSONPath in variables.

Environment variables

Environment variables let you store a set of environment definitions inside your project. For example, instead of providing a hostname in your request explicitly, you can create the {{host}} variable in different environments: a local hostname in the development environment and a public hostname in the production environment. You can then use the Run with list on the top of the current .http file editor to select an environment:

Define environment variables

On top of the request's editor panel, in the Run with list, select where you want to add an environment:
- Select Add Environment to Public File… if you want the environment to be public. This will add the environment to the http-client.env.json file. This file can contain common variables such as host name, port, or query parameters, and is meant to be distributed together with your project.
- Select Add Environment to Private File… if you want the environment to be private. This will add the environment to the http-client.private.env.json file. This file might include passwords, tokens, certificates, and other sensitive information. The values of variables that are specified in the http-client.private.env.json file override the values in the public environment file.
tip
If necessary, you can create these files manually.

Populate the created files with the desired variables.

The following sample http-client.env.json environment file defines two environments: development and production. The additional http-client.private.env.json file holds the sensitive authorization data.

http-client.env.json

http-client.private.env.json

{
    "development": {
        "host": "localhost",
        "id-value": 12345,
        "username": "",
        "password": "",
        "my-var": "my-dev-value"
    },

    "production": {
        "host": "example.com",
        "id-value": 6789,
        "username": "",
        "password": "",
        "my-var": "my-prod-value"
    }
}

The example HTTP request is as follows:

GET http://{{host}}/api/json/get?id={{id-value}}
Authorization: Basic {{username}} {{password}}
Content-Type: application/json

{
    "key": "{{my-var}}"
}

Before you execute the request, IntelliJ IDEA lets you choose an execution environment using the Run with list on top of the request's editor panel.

Depending on your choice, the resulting request will be one of the following:

development

production

GET http://localhost/api/json/get?id=12345
Authorization: Basic dev-user dev-password
Content-Type: application/json

{
    "key": "my-dev-value"
}

Manage multiple environment files

root/http-client.env.json # public file with 'dev' environment and 'host' variable
root/service1/http-client.private.env.json # private file with 'dev' environment and "key": "myKey1" variable
root/service2/http-client.private.env.json # private file with 'dev' environment and "key": "myKey2" variable

An .http file stored in the service1 directory will use the myKey1 value for the key variable when you select the dev environment. An .http file stored in the service2 directory will use the myKey2 value for the key variable.

If the private files contain the host variable, the .http files will use its value because private files take precedence over public files. Otherwise, they will use the value from the public file.

In-place variables

To create an in-place variable, type @ followed by the name of the variable above the HTTP method section. For example:

@myhost = example.org

GET {{myhost}}/users

###
GET {{myhost}}/stats

Per-request variables

You can use the request.variables.set(variableName, variableValue) method to set values of variables used in HTTP requests. Write it in a pre-request script wrapped in {% ... %} above your HTTP request. For example:

< {%
    request.variables.set("firstname", "John")
%}
GET http://example.org/{{firstname}}

< {%
    const signature = crypto.hmac.sha256()
        .withTextSecret(request.environment.get("secret")) // get variable from http-client.private.env.json
        .updateWithText(request.body.tryGetSubstituted())
        .digest().toHex();
    request.variables.set("signature", signature)

    const hash = crypto.sha256()
        .updateWithText(request.body.tryGetSubstituted())
        .digest().toHex();
    request.variables.set("hash", hash)
%}
POST https://httpbin.org/post
X-My-Signature: {{signature}}
X-My-Hash: {{hash}}
Content-Type: application/json

Dynamic variables

Dynamic variables generate a value each time you run a request. Their names start with $:

POST http://localhost/api/post?id={{$uuid}}

{
    "time": {{$timestamp}},
    "price": {{$random.integer(10, 1000)}},
}

< {%
    const longUUID = $random.uuid
    request.variables.set("generatedQuery", longUUID)
%}
GET https://examples.http-client.intellij.net/get
    ?generatedQuery={{generatedQuery}}

> {%
    client.log(`Today is ${$isoTimestamp}`)
%}

System environment variables

To access them, use the {{$env.ENV_VAR}} syntax where ENV_VAR is the name of your environment variable. In pre-request handler scripts and response handler scripts, use them without curly braces, similarly to regular JavaScript variables. For example:

GET http://localhost:63345/{{$env.USER}}

> {%
    const myUser = $env.USER
    client.log(myUser)
%}

Iterate over collections in variables

For example, if you have a server that returns information about a book by its ID, you can assign a JSON array [1,2,3,4,5] to a variable id, and then use it in the body or URL part.

< {%
    request.variables.set("id", [1,2,3,4,5])
%}
GET http://localhost:8080/books/{{id}}

Similarly, you can use collections in the request body. In the following example, the HTTP Client will send three requests with different values in the body: name: Alice, name: Bob, and name: Charlie.

< {%
    request.variables.set("name", ["Alice", "Bob", "Charlie"])
%}
GET http://localhost:8080/users
Content-Type: application/json

{
  "name": {{name}}
}

Using JSONPath, you can also access specific parameters of JSON objects in an array. For example, in the following query, the HTTP Client will send requests for each name value for all objects within a variable called users.

GET http://localhost:8080/users/{{users[*].name}}

To get the current index in the loop in pre-request scripts and in response handler scripts, use the request.iteration() method. For example, 0 indicates that the first item of the array is being processed, and the first request is being sent.

### Use request.iteration()
< {%
    request.variables.set("clients", [ // test data
        {"id": 1, "firstName": "George", "lastName": "Franklin", balance: 100},
        {"id": 2, "firstName": "John", "lastName": "Doe", balance: 1500},
        {"id": 3, "firstName": "Eduardo", "lastName": "Rodriquez", balance: 10}
    ])
%}

POST https://examples.http-client.intellij.net/post
        Content-Type: application/json

{
  "clientId": {{$.clients..id}},
  "firstName": "{{$.clients..firstName}}",
  "lastName": "{{$.clients..lastName}}",
  "balance": "{{$.clients..balance}}"
}

> {%
  client.log(request.iteration()) // prints 0 for 1st request, 1 for 2nd, 2 for 3rd
  let current = request.variables.get("clients")[request.iteration()]
  client.test(`Account ${current.lastName} has initial balance ${current.balance}`, () => {
    let responseBalance = jsonPath(response.body, "$.json.balance")
    client.assert(responseBalance == current.balance)
  })
%}

To get the value by its index in the loop in pre-request scripts and in response handler scripts, use the request.templateValue(Integer) method.

### Use templateValue

< {%
    request.variables.set("books", [{
    "books": {
      "title": "Ulysses",
      "year": 1922
    }
  },
  {
    "books": {
      "title": "Dune",
      "year": 1965
    }}])
%}

GET http://localhost:8080/books
Content-Type: application/json

{
  "bookTitle": "{{$.books..title}}",
  "bookYear": "{{$.books..year}}"
}

> {%
  let bookTitle = request.templateValue(0)
  client.log(`book title is: ${bookTitle}`) // prints Ulysses in 1st request, Dune in 2nd
  client.log(request.iteration())

  let bookYear = request.templateValue(1)
  client.log(`book year is: ${bookYear}`) // prints 1922 in 1st request, 1965 in 2nd

%}

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 {% ... %}.

GET https://httpbin.org/get

> /path/to/responseHandler.js

GET https://httpbin.org/get

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

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:

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

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

>> myFolder/myFile.json

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

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

> {{$projectRoot}}/handler.js

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

Thanks for your feedback!

Was this page helpful?

Exploring the HTTP request syntax﻿

Use comments in HTTP requests﻿

Set names for HTTP requests﻿

Use short form for GET requests﻿

Compose several requests in a single file﻿

Break long requests into several lines﻿

tip

Before

After

note

Before

After

Access a web service with authentication﻿

note

Provide the request message body﻿

Use multipart/form-data content type﻿

tip

Disable following redirects﻿

Disable saving requests to requests history﻿

Disable saving received cookies to the cookies jar﻿

Disabling encoding﻿

Customize HTTP request timeouts﻿

note

Use variables﻿

Use a variable inside the request﻿

note

tip

Environment variables﻿

Define environment variables﻿

tip

note

Manage multiple environment files﻿

In-place variables﻿

Per-request variables﻿

Dynamic variables﻿

More dynamic variables﻿

System environment variables﻿

Iterate over collections in variables﻿

Example of request.iteration()﻿

Example of request.templateValue()﻿

Handle the response﻿

Redirect the response﻿

note

Exploring the HTTP request syntax

Use comments in HTTP requests

Set names for HTTP requests

Use short form for GET requests

Compose several requests in a single file

Break long requests into several lines

Access a web service with authentication

Provide the request message body

Use multipart/form-data content type

Disable following redirects

Disable saving requests to requests history

Disable saving received cookies to the cookies jar

Disabling encoding

Customize HTTP request timeouts

Use variables

Use a variable inside the request

Environment variables

Define environment variables

Manage multiple environment files

In-place variables

Per-request variables

Dynamic variables

More dynamic variables

System environment variables

Iterate over collections in variables

Example of request.iteration()

Example of request.templateValue()

Handle the response

Redirect the response