How to Send an HTTP Header With curl
A custom request header is added to curl with the -H option.
The option takes one header line in name: value form, and repeating the option adds more headers to the same request.
The single-header command
Pass the header name, a colon, and the value as one quoted argument after -H. The example below sends a GET request to the HTTPBin echo service with a custom header. The echo endpoint returns the headers the server received, so you can check the result directly.
Adding more than one header
Repeat -H once per header. Each occurrence contributes one header line to the request; the order of the options does not change the meaning of the headers.
What curl and HTTP headers are
curl is an open-source command-line client for moving data to and from servers. It handles HTTP along with FTP, SMTP, and other protocols, which makes it a common way to test APIs and download files. An HTTP header is a key-value pair carried in a request or a response. Headers describe things such as content type, content length, cookies, authentication details, and the client type.
Checklist before you send
- Decide whether you are setting a request header (sent by curl) or reading a response header (returned by the server). -H sets request headers.
- Keep the header name and value in a single argument: -H "name: value".
- Quote values that contain spaces or shell-special characters.
- Add one -H per header rather than combining several headers in one argument.
- Use an echo endpoint when you need to confirm exactly what arrived at the server.
- Do not put secrets in shell history; prefer a file or environment variable when the value is sensitive.
Field map for the -H argument
The -H option has three parts. The header name is the field identifier, such as custom-header. The colon separates the name from the value. The value is the text after the colon, such as custom-value. In the echo response, the field appears with its canonical capitalization, so a request header written as custom-header may be returned as Custom-Header. The Host and User-Agent fields in the response are added by curl or the server, not by your -H option.
Why a header may not appear where you expect
Two different failures look similar. A malformed -H argument, such as a missing colon, means curl never sends the header you intended. A correctly sent header may still be absent from a response body if the endpoint does not echo request headers. Use an echo endpoint to separate the two cases: if the header appears in the echoed request, curl sent it; if it does not, check the argument syntax before changing the server or the URL.
Frequently asked questions
How do I send more than one HTTP header with curl?
Use the -H option once for each header. Each occurrence adds one header line to the request.
Does curl -H set a request header or a response header?
It sets a request header. Response headers are produced by the server and can be inspected separately.
Why is my custom header missing from the response?
The endpoint may not echo request headers back. Test against an echo service that returns the received headers, and check that the -H argument contains a colon between name and value.
curl {{HTTPBIN_BASE_URL}}/headers?json \
-H "custom-header: custom-value"
{
"headers": {
"Custom-Header": "custom-value",
"Host": "httpbin.scrapingbee.com",
"User-Agent": "curl/7.86.0"
}
}
curl {{HTTPBIN_BASE_URL}}/headers?json \
-H "custom-header: custom-value" \
-H "another-header: another-value"