cowboy_req:uri - Reconstructed URI


uri(Req :: cowboy_req:req())       -> uri(Req, #{})
uri(Req :: cowboy_req:req(), Opts) -> URI :: iodata()

Opts :: #{
    scheme   => iodata()           | undefined,
    host     => iodata()           | undefined,
    port     => inet:port_number() | undefined,
    path     => iodata()           | undefined,
    qs       => iodata()           | undefined,
    fragment => iodata()           | undefined

Reconstruct the effective request URI, optionally modifying components.

By default Cowboy will build a URI using the components found in the request. Options allow disabling or replacing individual components.



The Req object.


Map for overriding individual components.

To replace a component, provide its new value as a binary string or an iolist. To disable a component, set its value to undefined.

As this function always returns a valid URI, there are some things to note:

  • Disabling the host also disables the scheme and port.
  • There is no fragment component by default as these are not sent with the request.
  • The port number may not appear in the resulting URI if it is the default port for the given scheme (http: 80; https: 443).

Return value

The reconstructed URI is returned as an iolist or a binary string.


  • 2.0: Individual components can be replaced or disabled.
  • 2.0: Only the URI is returned, it is no longer wrapped in a tuple.
  • 2.0: Function introduced. Replaces host_url/1 and url/1.


With an effective request URI we can have:

Protocol relative form
%% //
cowboy_req:uri(Req, #{scheme => undefined}).
Serialized origin for use in the origin header
cowboy_req:uri(Req, #{path => undefined, qs => undefined}).
HTTP/1.1 origin form (path and query string only)
%% /path/to/res?edit=1
cowboy_req:uri(Req, #{host => undefined}).
Add a fragment to the URI
cowboy_req:uri(Req, #{fragment => <<"errors">>}).
Ensure the scheme is HTTPS
cowboy_req:uri(Req, #{scheme => <<"https">>}).
Convert the URI to a binary string

See also

cowboy_req(3), cowboy_req:scheme(3), cowboy_req:host(3), cowboy_req:port(3), cowboy_req:path(3), cowboy_req:qs(3)

Cowboy 2.7 Function Reference


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.