Curl With Headers

A “[.inline-code]curl[.inline-code] request header” is an HTTP header that can be used in an HTTP request to provide additional context and metadata, so that the server can tailor the way it processes the request and sends a response.

The short answer

To set a single header when sending a request with [.inline-code]curl[.inline-code], you can use the [.inline-code]-H[.inline-code] or [.inline-code]--header[.inline-code] flag as follows:

 $ curl -H "<header>" URL

Where [.inline-code]<header>[.inline-code] is an HTTP header composed of a name and a value in the following format: [.inline-code]name: value[.inline-code]. For example: [.inline-code]"Content-Type: plain/text"[.inline-code].

[#curl-mult-headers][.inline-code]curl[.inline-code] with multiple headers at once[#curl-mult-headers]

To pass multiple headers at once with [.inline-code]curl[.inline-code], you can simply repeat the [.inline-code]-H[.inline-code] flag for each header you want to add to the HTTP request as follows:

 $ curl -H "<header1>" -H "<header2>" URL

[#recall-syntax]Easily retrieve this command using Warp’s AI Command Search[#recall-syntax]

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Search feature:

Entering [.inline-code]curl send headers json token[.inline-code] in the AI Command Search will prompt a [.inline-code]curl[.inline-code] command that includes the [.inline-code]Content-Type[.inline-code] and the [.inline-code]Authorization[.inline-code] headers, which can then quickly be inserted into your shell by doing [.inline-code]CMD+ENTER[.inline-code].

[#examples]Examples of common use cases for [.inline-code]curl[.inline-code] headers[#examples]

Here are a few examples of commonly used HTTP headers when sending requests with [.inline-code]curl[.inline-code].

[#auth-requests]Sending authenticated requests[#auth-requests]

Since many APIs require requests to be authenticated, to access protected data or perform sensitive operations, you can use the [.inline-code]Authorization[.inline-code] header to send your credentials alongside with the request itself.

Here is an example of a [.inline-code]curl[.inline-code] GET request with an authorization header:

 $ curl -H "Authorization: Bearer <token>" 
  https://api.example.com/user/profile

You can also read our other articles if you want to learn more about sending authentication headers and performing basic authentication with curl.

[#specifying-payload]Specifying the payload encoding of the request[#specifying-payload]

Another common use case for sending headers with `curl` is to specify the encoding of the payload contained in the request. This is useful when sending data in a specific format such as JSON or URL-encoded, to indicate to the server which parsing method to use.

Here is an example of a [.inline-code]curl[.inline-code] POST request with a content-type header:

 $ curl -X POST -H "Content-Type: application/json" 
  -d '{"city":"paris"}' https://api.weather.com/forecast

[#specifying-requirements]Specifying client requirements for the response[#specifying-requirements]

Here's a more complex example with multiple headers used to indicate to the server how it should format its response before sending it back to the client.

 $ curl -H "Accept: application/json" -H "Accept-Language: en-US" 
  -H "Cache-Control: max-age=3600" https://api.example.com

Where:

• The "Accept" header indicates that the response should be in the JSON format.
• The "Accept-Language" header indicates that the response should be in American English.
• The "Cache-Control" header indicates that the response should not be older than 3600 seconds (i.e. 1 hour).