The low-level API and the request struct.

Req is composed of:

• Req - the high-level API

• Req.Request - the low-level API and the request struct (you're here!)

• Req.Auth, …, Req.Steps - a collection of built-in steps.

• Req.Test - the testing conveniences

The low-level API and the request struct is the foundation of Req's extensibility. Virtually all of the functionality is broken down into individual pieces - steps. See "Steps & Step Wrappers" section for more information.

To make using custom steps by others even easier, they can be packaged up into plugins. See "Writing Plugins" section for more information.

The Request Struct

Public fields are:

• :method - the HTTP request method.

• :url - the HTTP request URL.

• :headers - the HTTP request headers. The header names should be downcased. See also "Headers" section in Req module documentation.

• :body - the HTTP request body.

  Can be one of:

  • iodata - eagerly send request body

  • enumerable - stream request body

  • req_body_fun - stream request body chunks from a 1-arity function.

    Only supported in Req.stream/4. The function receives the accumulator passed to Req.stream/4.

    It should return one of:

    • {:data, chunk, acc} - emit request body chunk.

    • {:done, chunk, acc} - emit the final request body chunk. acc is passed to the response streaming function.

    • {:done, acc} - request body is done. acc is passed to the response streaming function.

    • {:halt, acc} - cancel request. On HTTP/1, this closes the connection.

    • {:error, exception, acc} - cancel request and return {:error, exception, resp, acc} from Req.stream/4.

• :into - where to send the response body. It can be one of:

  • nil - (default) read the whole response body and store it in the response.body field.

  • collectable - stream response body into a Collectable.t/0. For example:

    into: File.stream!("path")

    Note that the collectable is only used, if the response status is 200. In other cases, the body is accumulated and processed as usual.

  • :self - stream response body into the current process mailbox. The response body is set to a Req.Response.Async struct that consumes the messages.

  Note: Req.stream/4 does not support :into option.

• :options - the options to be used by steps. The exact representation of options is private. Calling request.options[key], put_in(request.options[key], value), and update_in(request.options[key], fun) is allowed. get_option/3 and delete_option/2 are also available for additional ways to manipulate the internal representation.

• :halted - whether the request pipeline is halted. See halt/2.

• :adapter - the adapter that makes the actual HTTP request. Defaults to Req.Finch.

• :request_steps - the list of request steps

• :private - a map reserved for libraries and frameworks to use. The keys must be atoms. Prefix the keys with the name of your project to avoid any future conflicts. The req_ prefix is reserved for Req.

The Low-level API

Most Req users would use it like this:

Req.get!("https://api.github.com/repos/wojtekmach/req").body["description"]
#=> "Req is a batteries-included HTTP client for Elixir."

Here is the equivalent using the low-level API:

req =
  Req.Request.new(
    url: "https://api.github.com/repos/wojtekmach/req"
  )
  |> Req.Request.register_options(
    # ...
    :decoders,
    # ...
  )
  |> Req.Request.prepend_request_steps(
    # ...
    decode: Req.Decode,
    # ...
  )

Req.get!(req).body["description"]
#=> "Req is a batteries-included HTTP client for Elixir."

In other words, Req.new/1, Req.get/1, and friends start with all the built-in steps and options but Req.Request.new/1 starts with a blank slate!

Steps & Step Wrappers

The simplest building blocks are steps, functions that take and return a request. For example:

defmodule MyApp do
  def put_user_agent(%Req.Request{} = req) do
    if user_agent = req.options[:user_agent] do
      Req.Request.put_header(req, "user-agent", user_agent)
    else
      req
    end
  end
end

req =
  Req.Request.new()
  |> Req.Request.register_options([:user_agent])
  |> Req.Request.prepend_request_steps(
    put_user_agent: &MyApp.put_user_agent/1,
  )

resp =
  Req.get!(
    req,
    url: "https://httpbingo.org/user-agent",
    user_agent: "foo"
  )

JSON.decode!(resp.body)      # We used Req.Request.new() so we're not using built-in decoding.
#=> %{"user-agent" => "foo"}

Next up, we have step wrappers, they additionally take acc, fun, state, and next. next is a function representing the rest of the processing pipeline, including hitting the network.

The simplest possible wrapper just calls the next one:

fn req, acc, fun, state, next ->
  next.(req, acc, fun, state)
end

Here's another example:

defmodule MyApp do
  def expect_successful(req, acc, fun, state, next) do
    fun = fn
      {:status, status}, resp, acc, state when status in 200..299 ->
        fun.({:status, status}, resp, acc, state)

      {:status, status}, resp, acc, state ->
        err = RuntimeError.exception("unexpected status #{status}")
        {{:error, err}, resp, acc, state}

      event, resp, acc, state ->
        fun.(event, resp, acc, state)
    end

    next.(req, acc, fun, state)
  end
end

Req.new("https://httpbingo.org/status/404")
|> Req.Request.prepend_request_steps(expect: &MyApp.expect_successful/5)
|> Req.request!()

More complicated wrappers will maintain their state.

The contract for wrappers is:

wrapper :: (req, acc, fun, state, next ->
             {:ok, resp, acc, state}
             | {:halt, resp, acc, state}
             | {{:error, err}, resp, acc, state})

fun is:

fun :: (event, resp, acc, state ->
          {:ok, resp, acc, state}
          | {:halt, resp, acc, state}
          | {{:error, err}, resp, acc, state})
when req: Req.Request.t(),
     resp: Req.Response.t(),
     err: Exception.t(),
     acc: term(),
     state: term(),
     event:
       {:status, non_neg_integer()}
       | {:headers, [{binary(), binary()}]}
       | {:data, term()}
       | {:trailers, [{binary(), binary()}]}

next is:

next :: (req, acc, fun, state ->
           {:ok, resp, acc, state}
           | {:halt, resp, acc, state}
           | {{:error, err}, resp, acc, state})
when req: Req.Request.t(),
     resp: Req.Response.t(),
     err: Exception.t(),
     acc: term(),
     state: term()

Here's another example, a simplistic redirect feature:

defmodule MyApp do
  @redirect_statuses [301, 302, 307, 308]

  def redirect(req, acc, fun, state, next) do
    next.(req, acc, wrap(fun, next), state)
  end

  defp wrap(fun, next) do
    fn
      {:headers, _headers}, resp, acc, state
      when resp.status in @redirect_statuses ->
        [location] = Req.Response.get_header(resp, "location")
        req = resp.request
        req = update_in(req.url, &URI.merge(&1, location))

        with {:ok, resp, acc, state} <- next.(req, acc, wrap(fun, next), state) do
          {:halt, resp, acc, state}
        end

      event, resp, acc, state ->
        fun.(event, resp, acc, state)
    end
  end
end

Req.Request.new(url: "https://httpbingo.org/redirect/3")
|> Req.Request.prepend_request_steps(redirect: &MyApp.redirect/5)
|> Req.request!()

acc and fun are the ones given to Req.stream(req, acc, fun, options \\ []). Most steps usually just pass them through unchanged. However, if you want to process response as it comes in, you'd want to maintain your own state. Here's a simplistic streaming NDJSON decoder:

defmodule MyApp do
  def decode(%Req.Request{} = req, acc, fun, state, next) do
    fun = fn
      {:data, data}, resp, acc, [buffer | state] ->
        {lines, [buffer]} = Enum.split(String.split(buffer <> data, "\n"), -1)
        values = for line <- lines, line != "", do: JSON.decode!(line)
        {tag, resp, acc, state} = fun.({:data, values}, resp, acc, state)
        {tag, resp, acc, [buffer | state]}

      event, resp, acc, [buffer | state] ->
        {tag, resp, acc, state} = fun.(event, resp, acc, state)
        {tag, resp, acc, [buffer | state]}
    end

    {tag, resp, acc, [_buffer | state]} = next.(req, acc, fun, ["" | state])
    {tag, resp, acc, state}
  end
end

req =
  Req.Request.new()
  |> Req.Request.prepend_request_steps(decode: &MyApp.decode/5)

Req.stream(
  req,
  nil,
  fn values, _resp, acc ->
    IO.inspect(Enum.map(values, &Map.take(&1, ["id"])))
    {:cont, acc}
  end,
  url: "https://httpbingo.org/stream/3"
)
# Output: [%{"id" => 0}]
# Output: [%{"id" => 1}]
# Output: [%{"id" => 2}]

Adapters

By default Req uses Finch (via Req.Finch) and supports arbitrary adapters implementing Req.Adapter behaviour. Req adapters are closely related to step wrappers described in previous section.

Plugins

Custom steps can be packaged into plugins so that they are even easier to use by others. By convention, a plugin module exports a def attach(%Req.Request{} = req) function:

Here's an example plugin:

defmodule PrintHeaders do
  @doc """
  Prints request and response headers.

  ## Request Options

    * `:print_headers` - if `true`, prints the headers. Defaults to `false`.

  """
  def attach(%Req.Request{} = req) do
    req
    |> Req.Request.register_options([:print_headers])
    |> Req.Request.append_request_steps(print_headers: __MODULE__)
  end

  def stream(%Req.Request{} = req, acc, fun, state, next) do
    if req.options[:print_headers] do
      for {name, value} <- Req.get_headers_list(req) do
        IO.puts(["> ", name, ": ", value])
      end

      with {:ok, resp, acc, state} <- next.(req, acc, fun, state) do
        for {name, value} <- Req.get_headers_list(resp) do
          IO.puts(["< ", name, ": ", value])
        end

        {:ok, resp, acc, state}
      end
    else
      next.(req, acc, fun, state)
    end
  end
end

And here is how we can use it:

req = Req.new() |> PrintHeaders.attach()

resp = Req.get!(req, url: "https://httpbingo.org/json")
resp.status
#=> 200

resp = Req.get!(req, url: "https://httpbingo.org/json", print_headers: true)
# Output: > accept-encoding: br, gzip
# Output: > user-agent: req/0.3.0-dev
# Output: < date: Wed, 12 Aug 2026 09:07:49 GMT
# Output: < content-type: application/json
# ...
resp.status
#=> 200

As you can see a plugin is simply a module. While this is not enforced, the plugin should follow these conventions:

• It should export an attach/1 function that takes and returns the request struct

• The attach functions mostly just adds steps and it is the steps that do the actual work

• A user should be able to attach your plugin alongside other plugins. For this reason, plugin functionality should usually only happen on a specific "trigger": on a specific option, on a specific URL scheme or host, etc. This is especially important for plugins that perform authentication; you don't want to accidentally expose a token from service A when a user makes request to service B.

• If your plugin supports custom options, register them with register_options/2

• Sometimes it is useful to pass options when attaching the plugin. For that, export an attach/2 function and call merge_options/2. Remember to first register options before merging!