How to Show and Send HTTP Headers with cURL

cURL is a CLI tool for performing data transmission using different protocols, including HTTP and HTTPS. HTTP headers are crucial when establishing client-server communication with a web server or application. Headers contain metadata, such as authentication tokens, caching information, and content type.

Knowing how to show and send HTTP headers using cURL is essential when working with APIs and testing server responses.

This guide explains how to show, change, and save HTTP headers using cURL.

Prerequisites

• cURL installed.
• Access to the command line/terminal.

Sending HTTP Headers with cURL: Use Cases

HTTP headers contain information about client requests and server responses. Customizing these values is necessary in some situations, including:

• Authentication and authorization. Many APIs require sending tokens, API keys, or credentials. The Authorization header helps access these protected resources. For example, APIs often require sending a Bearer token to perform OAuth2 authentication.
• Format customization. Custom headers help control the request body (Content-Type) or response (Accept) format. These headers are essential when an API supports multiple formats, such as JSON, XML, HTML, and others.
• Custom metadata. Some APIs require including custom headers to pass additional context, facilitate debugging, or serve other purposes. These headers are often vendor-specific and may include unique identifiers, tracking tokens, or session information. Traditionally, these headers have the prefix X- (e.g., X-Custom-Header). However, this is not a requirement in modern conventions.
• Testing. Developers and software testers use custom headers to see how a server responds to various inputs. They can simulate various client requests, such as missing headers, invalid tokens, and incorrect cache-control settings, among others.

Knowing how to send, edit, and manage HTTP headers with cURL is essential for developers, testers, and system administrators who work with APIs and web servers.

How to Send HTTP Headers Using cURL

There are different ways to send HTTP headers using cURL. The syntax differs depending on whether the headers are default, custom, empty, or if there are multiple headers.

The sections below cover different examples of how to send HTTP headers using the curl command.

How to Send Default Headers

cURL includes several headers that help establish a connection with the server. These headers are provided by default with every request and do not need to be explicitly defined.

For example, the following command sends a cURL request with default headers:

curl -v https://httpbin.org/

The -v option shows a detailed output with request and response details in the terminal. The request headers have a > prefix, like in the following example:

> GET / HTTP/2
> Host: httpbin.org
> User-Agent: curl/8.5.0
> Accept: */*

The default headers are:

• Host. The domain name of the server.
• User-Agent. The cURL client and version.
• Accept. The content type the client accepts (*/* means any content type).

The headers ensure a correct response from the server and that it's in the correct format.

How to Send Custom Headers

cURL allows you to add custom headers using the -H or --header flag. APIs that require specific headers for authentication, content type, or other metadata require using these flags.

For example, to send a custom Authorization header, use:

curl -H "Authorization: Bearer YOUR_TOKEN" https://httpbin.org/headers

The command simulates sending an OAuth2.0 bearer token, while the /headers endpoint displays the headers the server received. Modify the header name and value according to the application or API requirements.

How to Send Multiple Headers

To send multiple headers in a single cURL request, repeat the -H or --header option for each header. For example:

curl -H "Authorization: Bearer YOUR_TOKEN" -H "X-Custom: MY_HEADER" https://httpbin.org/headers

The command sends two headers simultaneously:

• Authorization header with an example access token.
• X-Custom header with a custom value.

Use this method when an API requires several headers. Include as many headers as are required.

How to Send Empty Headers

cURL allows sending empty HTTP headers to clear default headers. Provide the header name, followed by no value:

curl -H "Accept:" https://httpbin.org/headers

The command removes the Accept header and its default value (*/*).

How to Edit Default Headers with cURL

cURL allows overriding or suppressing default headers. Use the -H option and provide a custom value to one (or more) default header:

curl -H "User-Agent: MyAgent/1.0" https://httpbin.org/headers

The command overrides the default User-Agent value with the custom value. Combine multiple headers in one request to override some and remove other values for complete flexibility.

How to Show Headers Sent by cURL

It's helpful to see which headers cURL sends in a request, especially during troubleshooting and testing. The first way to inspect the request and response is with the -v (verbose) option:

curl -v https://httpbin.org/

The request headers are prefixed with >, while the response headers are shown immediately after and begin with <.

Another way to display headers is to use --trace or --trace-ascii options. The first option dumps the entire log (including binary data), while the second is human-readable.

The syntax is:

curl --trace-ascii - https://httpbin.org/

Header data is after "=> Send header" and "<= Recv header" lines. The command outputs the log data as stdout (-). Specify a file name to save the logs to a file instead.

How to Save Headers to a File?

cURL provides the -D or --dump-header option to save a HTTP response header to a file. To save only the response headers, provide the option followed by the file name:

curl -D data.txt https://httpbin.org/

The command saves the response headers to data.txt and prints the response in the terminal. To view the file's contents, use the cat command or a command-line text editor:

cat data.txt

The command's output shows the file's contents in the terminal.

Conclusion

This guide explained how to use cURL to show, modify, and send HTTP headers when interacting with an API.

Next, see how to send a cURL POST request.