TopolearnMost API and caching problems are visible in headers, so seeing and setting them is essential.
HTTP responses have a status line, headers and a body. curl shows only the body unless you ask.
-iincludes the response status line and headers before the body.-Isends a HEAD request: headers only, no body. Handy for checking status,Content-Type,Content-Lengthor caching headers of large files.-v(verbose) shows everything: lines starting with*are curl's own info (DNS, connection, TLS),>lines are the request you sent,<lines the response headers. Verbose output goes to stderr, so the body can still be piped.
To send headers, use -H 'Name: value', as many times as needed. Headers curl sets by default (such as User-Agent: curl/8.x and Accept: */*) are replaced if you provide them, and removed with an empty value: -H 'Accept:'. -A is a shortcut for the User-Agent.
A quick mental model of -v output for an HTTPS request: name resolution, TCP connect, TLS handshake (certificate details), then the request lines, then the response. When "it works in the browser but not with curl", compare the headers your browser sends (devtools can "Copy as cURL") with yours.
Note that -I really sends HEAD, which some servers handle differently from GET; to see headers of a real GET, use -i or -s -D - -o /dev/null.
Example
curl -i https://example.com # HTTP/2 200 + headers + body
curl -I https://example.com/big.iso # HEAD: headers only
curl -v https://api.example.com/health
# * Connected to api.example.com (203.0.113.7) port 443
# > GET /health HTTP/2
# > User-Agent: curl/8.16.0
# < HTTP/2 200
# < content-type: application/json
curl -H 'Accept: application/json' -H 'X-Request-Id: abc123' https://api.example.com/items
curl -sS -D - -o /dev/null https://example.com # GET, print only headersRemember
- -i adds response headers, -I sends HEAD, -v shows the whole exchange
- -H 'Name: value' sets request headers; -H 'Name:' removes one
- In -v output: * info, > request, < response
Watch out for
- Using -I to debug an endpoint that behaves differently for HEAD than GET.