Modify the HTTP request
As described earlier, each HTTP transfer starts with curl sending a HTTP request. That request consists of a request line and a number of request headers, and this chapter details how you can modify all of those.
The first line of the request includes the method - sometimes also referred to as the verb. When doing a simple GET request as this command line would do:
curl http://example.com/file
…the initial request line looks like this:
GET /file HTTP/1.1
You can tell curl to change the method into
something else by using the -X
or --request
command-line options followed by the actual
method name. You can, for example, send a DELETE
instead of GET
like this:
curl http://example.com/file -X DELETE
This command-line option only changes the
text in the outgoing request, it does not
change any behavior. This is particularly
important if you, for example, ask curl to
send a HEAD with -X, as HEAD is specified to send all the
headers a GET response would get but never
send a response body, even if the headers
otherwise imply that one would come. So,
adding -X HEAD
to a command line that would otherwise do a
GET will cause curl to hang, waiting for a
response body that will not come.
When asking curl to perform HTTP transfers,
it will pick the correct method based on the
option so you should only rarely have to
explicitly ask for it with -X. It should also be noted that when curl
follows redirects like asked to with -L, the request method set with -X
will be sent even on the subsequent
redirects.
In the example above, you can see how the
path section of the URL gets turned into /file
in the request line. That is called the
request target. That's the resource
this request will interact with. Normally
this request target is extracted from the
URL and then used in the request and as a
user you do not need to think about
it.
In some rare circumstances, user may want
to go creative and change this request
target in ways that the URL does not really
allow. For example, the HTTP OPTIONS method
has a specially define request target for
magic that concerns the server
and not a specific path, and it uses *
for that. Yes, a single asterisk.
There's no way to specify a URL for
this, so if you want to pass a single
asterisk in the request target to a server,
like for OPTIONS, you have to do it like
this:
curl -X OPTIONS --request-target "*" http://example.com/
A URL may contain an anchor, also known as
a fragment, which is written with a pound
sign and string at the end of the URL. Like
for example http://example.com/foo.html#here-it-is. That fragment part, everything from the
pound/hash sign to the end of the URL, is
only intended for local use and will not be
sent over the network. curl will simply
strip that data off and discard it.
In a HTTP request, after the initial
request-line, there will typically follow a
number of request headers. That's a set
of name: value
pairs that ends with a blank line that
separates the headers from the following
request body (that sometimes is
empty).
curl will by default and on its own account
pass a few headers in requests, like for
example Host:, Accept:, User-Agent:
and a few others that may depend on what the
user asks curl to do.
All headers set by curl itself can be
overridden, replaced if you will, by the
user. You just then tell curl's -H
or --header
the new header to use and it will then
replace the internal one if the header field
matches one of those headers, or it will add
the specified header to the list of headers
to send in the request.
To change the Host:
header, do this:
curl -H "Host: test.example" http://example.com/
To add a Elevator: floor-9
header, do this:
curl -H "Elevator: floor-9" http://example.com/
If you just want to delete an internally generated header, just give it to curl without a value, just nothing on the right side of the colon.
To switch off the User-Agent:
header, do this:
curl -H "User-Agent:" http://example.com/
Finally, if you then truly want to add a header with no contents on the right side of the colon (which is a rare thing), the magic marker for that is to instead end the header field name with a semicolon. Like this:
curl -H "Empty;" http://example.com
When a user clicks on a link on a web page
and the browser takes the user away to the
next URL, it will send the new URL a Referer:
header in the new request telling it where
it came from. That is the referer header.
And yes, referer is misspelled but
that's how it is supposed to be!
With curl you set the referer header with -e
or --referer, like this:
curl --referer http://comes-from.example.com https://www.example.com/
The User-Agent is a header that each client can set in the request to inform the server which user-agent it is. Sometimes servers will look at this header and determine how to act based on its contents.
The default header value is
'curl/[version]', as in User-Agent: curl/7.54.1
for curl version 7.54.1.
You can set any value you like, using the
option -A
or --user-agent
plus the string to use or, as it's just
a header, -H "User-Agent:
foobar/2000".
As comparison, a recent test version of Firefox on a Linux machine sent this User-Agent header:
User-Agent: Mozilla/5.0 (X11; Linux
x86_64; rv:58.0) Gecko/20100101
Firefox/58.0
HTTP supports conditional requests. They are requests that contain a condition in the sense that it asks the server to only deliver a response body if the associated condition evaluates true.
A useful condition is time. For example, ask the server to only deliver a response if the resource has been modified after a particular time:
curl --time-cond "1 Jul 2011" https://www.example.org/file.html
curl can also reverse the condition. Only get the file if it is older than the given date by prefixing the date with a dash:
curl --time-cond "-1 Jul 2011" https://www.example.org/file.html
The date parser is liberal and will accept most formats you can write the date, and you can of course also specify it complete with a time:
curl --time-cond "Sun, 12 Sep 2004 15:05:58 -0700" https://www.example.org/file.html
curl can also get the time stamp off a local file as a shortcut. No need to download the file again if it has not changed on the server, right? If the string does not match a time or date, curl checks if there's a file named like that, and if so gets the time from its modification time.
curl --time-cond file https://www.example.org/file.html -o file
