How to set custom headers in cURL requests

HTTP headers carry metadata about requests and responses. Adding custom headers modifies how clients and servers interact, enabling fine-grained control for authentication, content negotiation, or testing scenarios.

By using --header, it’s possible to inject tokens, change user agents, or provide instructions to the server. This is especially useful when working with APIs requiring custom fields or testing request variants.

Custom headers help emulate different client conditions, verify server logic, and support automated testing. With scripting, these configurations become repeatable and robust.

1. Open a terminal.
2. Make a basic request and observe default headers.

   $ curl http://example.com/api --verbose
   > GET /api HTTP/1.1
   > Host: example.com
   > User-Agent: curl/...
   > Accept: */*

   --verbose shows the default request headers.

3. Add a custom header with --header.

   $ curl --header "User-Agent: MyTestApp/1.0" http://example.com/api --verbose
   > User-Agent: MyTestApp/1.0

   Set a custom User-Agent or other headers as needed.

4. Add multiple headers by repeating --header.

   $ curl --header "User-Agent: MyTestApp/1.0" --header "Authorization: Bearer abc123" http://example.com/api --verbose
   > Authorization: Bearer abc123

   Combine headers for complex requests.

5. Store headers in a config file and load them with --config.

   $ echo 'header = "X-Custom-Header1: Value1"' > headers.txt
   $ curl --config headers.txt http://example.com/api --verbose
   > X-Custom-Header1: Value1

   --config simplifies recurring requests with predefined headers.