Curl Send Header Example — Add, Replace, Remove

The command

curl https://httpbin.org/headers \
  -H "X-Request-Id: 7f3a9c" \
  -H "Accept-Language: en-GB"

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

What the flags do

Flag	What it does
`-H "Name: value"`	Add a header, or replace one curl would have sent.
`-H "Name:"`	Remove a header curl sends by default.
`-H "Name;"`	Send the header with an empty value.
`-H @file`	Read headers from a file, one per line (curl 7.55+).
`-v`	Show the request headers actually sent, on lines starting with `>`.

Add, replace, remove

Curl sends Host, User-Agent and Accept: */* on its own, and more once you add a body. Naming one of those in -H replaces it. Naming it with nothing after the colon removes it, which is how you test what an API does when a header is absent. A header that should be present but empty needs a semicolon instead of a colon, because "X-Flag:" already means "remove".

curl https://httpbin.org/headers \
  -H "Accept: application/json" \
  -H "User-Agent:" \
  -H "X-Empty;"

Checking what was sent

Do not assume; look. -v prints the outgoing request with each line prefixed >. An echo endpoint such as httpbin.org/headers shows the headers as the server received them, which also reveals anything a proxy added or removed on the way.

For a set of headers you reuse, put them in a file and pass -H @headers.txt, which keeps tokens out of your shell history.

curl -v -o /dev/null -H "X-Debug: 1" https://httpbin.org/get 2>&1 | grep "^>"

Common mistakes

Custom headers follow redirects. With -L, headers set by -H are sent to every host in the chain; think before attaching a secret to a URL that might redirect elsewhere.
Do not set Content-Length or Host by hand unless that is the thing under test. Curl computes them, and a wrong value produces hangs or 400s.
Quote the whole header. Unquoted, the space after the colon splits it into two arguments and curl treats the value as a URL.

Related curl examples

Curl Custom Headers Example

A custom header is one an application defines for itself: an API version, an idempotency key, a tenant, a request id.

Curl Content-Type Example

Content-Type tells the server how to parse the body you sent.

Curl User Agent Example

Every curl request announces itself as curl.

Curl Bearer Token Auth Header Example

A bearer token is a credential you present in a header; whoever holds it is treated as its owner.

All Curl Examples

49 worked examples, grouped by what you are trying to do.

More under Headers

References

curl man page: -H — Adding, replacing and removing request headers.
MDN: HTTP headers — A reference for every standard request and response header.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ

How do I send a header with curl?

Use -H "Name: value". Repeat the flag for each additional header.

How do I send multiple headers with curl?

Pass one -H flag per header, for example curl -H "Accept: application/json" -H "X-Api-Version: 2" URL.

How do I remove a default header in curl?

Pass the header name followed by a colon and nothing else, for example -H "Accept:" to stop curl sending its Accept header.