curl API Debugging Cheatsheet

Headers, JSON payloads, auth, timing, redirects, TLS and reproducible request evidence. Last updated August 31, 2026.

curl is one of the fastest ways to turn an API complaint into reproducible evidence. The official curl manual describes curl as a tool for transferring data with URLs at curl.se/docs/manpage.html. This Formalint cheatsheet focuses on practical debugging commands developers can copy into a terminal and adapt safely.

Start with a visible response

Use headers, status and body separately. A browser may hide details behind CORS or UI behavior, but curl can show the raw HTTP exchange.

curl -i https://api.example.com/health
curl -sS -D headers.txt -o body.json https://api.example.com/health
curl -sS -w "\nstatus=%{http_code} time=%{time_total}s\n" https://api.example.com/health

Send JSON without losing evidence

curl -sS -X POST https://api.example.com/customers \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{"name":"Ada Lovelace","email":"ada@example.com"}'

Format the response with the JSON Formatter, compare two responses with JSON Diff, and turn a stable example into a draft contract with the JSON Schema Generator.

Auth and token checks

Do not paste production tokens into public tickets or browser tools. Use short-lived test tokens and redact secrets in command history before sharing.

curl -i https://api.example.com/me \
  -H "Authorization: Bearer REPLACE_WITH_TEST_TOKEN"

curl -i https://api.example.com/admin \
  -H "Authorization: Bearer REPLACE_WITH_TEST_TOKEN" \
  -H "X-Request-Id: debug-20260831-001"

Timing and redirect evidence

Question	curl command	What it proves
Which status code returned?	`curl -I https://example.com/`	Headers and status without downloading the body.
Where does it redirect?	`curl -I -L https://example.com/`	Final URL, redirect chain and response headers.
Is the API slow?	`curl -w "%{time_total}\n" -o NUL -s https://example.com/`	Total request time on Windows PowerShell or CMD.
Is DNS or TLS the delay?	`curl -w "dns=%{time_namelookup} tls=%{time_appconnect} total=%{time_total}\n" -o /dev/null -s https://example.com/`	Timing split for Linux and Git Bash.

Debug a CORS preflight with curl

CORS is enforced by browsers, not curl, but curl can reproduce the preflight request that the browser sends before some cross-origin requests.

curl -i -X OPTIONS https://api.example.com/orders \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type,authorization"

Repeatable incident note

endpoint:
method:
environment:
request-id:
status:
headers saved:
body sample redacted:
expected:
observed:
next layer to inspect:

The best curl command for a production issue is the smallest command that captures method, URL, headers, payload shape, status, timing and a request ID without exposing secrets.