curl -H / --header: Set Request Headers
Headers are how you set content type, accept, and auth, and -H stacks.
Almost every API call needs at least one header. -H is repeatable and can also remove headers curl would send by default.
What it does
-H / --header adds a header to the request. Repeat it for multiple headers. To remove a header curl sends automatically, pass it with an empty value, for example -H 'Accept:'. To send a header with no value, end it with a semicolon, like -H 'X-Flag;'. Headers set with -H override curl defaults.
Common usage
curl -H 'Accept: application/json' https://api.example.com/x
curl -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d @body.json https://api.example.com/x
curl -H 'Accept:' https://api.example.com/x # remove the default Accept
curl -H 'X-Trace;' https://api.example.com/x # send empty headerFlags
| Flag | What it does |
|---|---|
| -H 'Name: value' | Add or override a request header (repeatable) |
| -H 'Name:' | Remove a header curl would send by default |
| -H 'Name;' | Send a header with an empty value |
| -A / --user-agent | Convenience flag for the User-Agent header |
| -b / --cookie | Convenience flag for the Cookie header |
In CI
Pass tokens through -H "Authorization: Bearer $TOKEN" with the variable from a secret, never a literal. Use double quotes around headers that contain a variable so the shell expands it, and single quotes for static headers to avoid accidental expansion.
Common errors in CI
A 401 or 403 usually means a missing or malformed Authorization header; print the header names (not the secret) with -v to confirm. curl: (1) Protocol "..." not supported appears when a stray newline from a multi-line header leaks into the URL.