Ktor 3.2.1 Help

Default request

The DefaultRequest plugin allows you to configure default parameters for all requests: specify a base URL, add headers, configure query parameters, and so on.

Add dependencies

DefaultRequest only requires the ktor-client-core artifact and doesn't need any specific dependencies.

Install DefaultRequest

To install DefaultRequest, pass it to the install function inside a client configuration block:

import io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.client.plugins.* //... val client = HttpClient(CIO) { install(DefaultRequest) }

Or call the defaultRequest function and configure required request parameters:

import io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.client.plugins.* //... val client = HttpClient(CIO) { defaultRequest { // this: DefaultRequestBuilder } }

Configure DefaultRequest

Base URL

DefaultRequest allows you to configure a base part of the URL that is merged with a request URL. For example, the url function below specifies a base URL for all requests:

defaultRequest { url("https://ktor.io/docs/") }

If you make the following request using the client with the above configuration, ...

val response: HttpResponse = client.get("welcome.html")

... the resulting URL will be the following: https://ktor.io/docs/welcome.html. To learn how base and request URLs are merged, see DefaultRequest.

URL parameters

The url function also allows you to specify URL components separately, for example:

  • an HTTP scheme;

  • a host name;

  • a base URL path;

  • a query parameter.

url { protocol = URLProtocol.HTTPS host = "ktor.io" path("docs/") parameters.append("token", "abc123") }

Headers

To add a specific header to each request, use the header function:

defaultRequest { header("X-Custom-Header", "Hello") }

To avoid duplicating headers, you can use the appendIfNameAbsent, appendIfNameAndValueAbsent, and contains functions:

defaultRequest { headers.appendIfNameAbsent("X-Custom-Header", "Hello") }

Unix domain sockets

You can build individual requests with Unix domain sockets, but you can also configure a default request with a socket parameter.

To do that, pass a unixSocket call with the path to the socket to the defaultRequest function, for example:

val client = HttpClient(CIO) // Sending a single request to a Unix domain socket val response: HttpResponse = client.get("/") { unixSocket("/tmp/test-unix-socket-ktor.sock") } // Setting up the socket for all requests from that client val clientDefault = HttpClient(CIO) { defaultRequest { unixSocket("/tmp/test-unix-socket-ktor.sock") } } val response: HttpResponse = clientDefault.get("/")

Example

The example below uses the following DefaultRequest configuration:

  • The url function defines an HTTP scheme, a host, a base URL path, and a query parameter.

  • The header function adds a custom header to all requests.

val client = HttpClient(CIO) { defaultRequest { url { protocol = URLProtocol.HTTPS host = "ktor.io" path("docs/") parameters.append("token", "abc123") } header("X-Custom-Header", "Hello") } }

The request below made by this client specifies a latter path segment only and applies parameters configured for DefaultRequest automatically:

val response: HttpResponse = client.get("welcome.html") println(response.status)

You can find the full example here: client-default-request.

11 July 2025