TL;DR
curl is the first tool for API debugging. Essentials: curl -sS URL, curl -X POST -H 'Content-Type: application/json' -d '{}' URL, curl -w '%{http_code}'.
Basic Requests
| Need | Command |
|---|---|
| GET with headers in output | curl -i URL |
| Silent mode | curl -sS URL |
| Headers only | curl -I URL |
| Follow redirects | curl -L URL |
| Save to file | curl -o file.txt URL / -O |
Sending Data
| Need | Command |
|---|---|
| POST JSON | curl -X POST -H 'Content-Type: application/json' -d '{"k":"v"}' URL |
| Form data | curl -d 'k=v&k2=v2' URL |
| Upload file | curl -F 'file=@./a.txt' URL |
| Custom header | curl -H 'Authorization: Bearer TOKEN' URL |
| Cookies | curl -b 'name=value' URL |
Useful Flags
| Flag | Purpose |
|---|---|
-w '%{http_code}\n' | Print status code only |
--max-time 10 | Timeout (seconds) |
--connect-timeout 5 | Connect timeout |
-k | Skip TLS verification (debug only) |
-x http://host:port | Use proxy |
-A 'UA' | Custom User-Agent |
Debugging Notes
- Status 000 = connection failure/timeout; add
--max-timeand-v. -vshows handshake and header details.curl -s -o /dev/null -w '%{http_code}'is the standard script pattern.
FAQ
Why does curl return 000?
000 means the connection failed or timed out — it is not an HTTP status code. Run curl -v URL to see where it stops, then add --connect-timeout 5 and --max-time 10; use -k only for debugging.
How do I send a POST request with JSON?
curl -X POST -H 'Content-Type: application/json' -d '{"k":"v"}' URL. Without the JSON content type, -d sends form-encoded data.
How do I download a file with curl?
Use curl -o file.txt URL to set the local filename, or curl -O URL to keep the remote name. Add -L to follow redirects and --max-time for large downloads.
How do I print only the HTTP status code?
curl -s -o /dev/null -w '%{http_code}' URL — the standard pattern for health checks.
How do I fix "SSL certificate problem" errors?
Update the system CA store (apt install ca-certificates or the OS update) instead of blindly using -k. Use --insecure only for debugging.
Sources
- curl docs (curl.se/docs/manpage.html)