curl: debugging APIs from the terminal
A handful of curl flags that are enough to call an API, inspect headers, measure timing, and find where a request goes wrong.
When an API returns something strange, I call it directly with curl to rule out errors on the client side. Here are the flags I use most.
Viewing headers and the request
By default curl only prints the body. -i also prints the status line and response headers:
curl -i https://api.example.com/users/1
-v also prints the request that was sent: lines starting with > are the request, < is the response, and * is connection info (DNS, TLS):
curl -v https://api.example.com/users/1
Sending JSON
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"name": "An"}'
With -d, curl automatically uses POST, so you only need -X for PUT, PATCH, and DELETE. Since curl 7.82 there is --json, which automatically sets Content-Type and Accept to application/json:
curl --json '{"name": "An"}' https://api.example.com/users
curl --json @body.json https://api.example.com/users
@ reads the body from a file.
Getting only the status code
curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/health
-s silences the progress meter, -o /dev/null discards the body, and -w prints a format string after the request finishes.
Measuring timing
curl -s -o /dev/null -w 'dns: %{time_namelookup}\nconnect: %{time_connect}\nttfb: %{time_starttransfer}\ntotal: %{time_total}\n' https://api.example.com/users
All of these numbers are measured from the start of the request, not per individual step. A large ttfb (time to first byte) with a small connect means the server is slow to process the request, not that the network is the problem.
Exit code when the server returns an error
When the server returns 404 or 500, curl still exits with code 0, because the request itself completed. Add -f to make it exit with code 22:
curl -sS -f https://api.example.com/nope
# curl: (22) The requested URL returned error: 404
-f also discards the error body. If you need to see the body, use --fail-with-body (since curl 7.76). -S goes together with -s so that error messages are still shown.
Other flags
-L: follow redirects (it doesn’t by default).-k: skip TLS certificate verification, only for development.--max-time 10: give up after 10 seconds.| jq .: format JSON so it’s easier to read.
In Chrome’s Network tab, right-click a request and choose Copy > Copy as cURL to get the equivalent curl command, including headers and cookies.