All Snippets
cURL Cheatsheet for API Testing
Essential cURL commands for testing REST APIs, handling auth, uploading files, and debugging HTTP requests from the terminal.
curl is the Swiss Army knife of HTTP requests. If you work with APIs, these patterns will cover 90% of your daily use.
Basic Requests
GET, POST, PUT, DELETEbash
| 1 | # Simple GET |
| 2 | curl https://api.example.com/users |
| 3 | |
| 4 | # POST with JSON body |
| 5 | curl -X POST https://api.example.com/users \ |
| 6 | -H "Content-Type: application/json" \ |
| 7 | -d '{"name": "Alice", "email": "alice@example.com"}' |
| 8 | |
| 9 | # PUT (update) |
| 10 | curl -X PUT https://api.example.com/users/42 \ |
| 11 | -H "Content-Type: application/json" \ |
| 12 | -d '{"name": "Alice Updated"}' |
| 13 | |
| 14 | # DELETE |
| 15 | curl -X DELETE https://api.example.com/users/42 |
Authentication
Common auth patternsbash
| 1 | # Bearer token |
| 2 | curl -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/me |
| 3 | |
| 4 | # Basic auth |
| 5 | curl -u username:password https://api.example.com/me |
| 6 | |
| 7 | # API key in header |
| 8 | curl -H "X-API-Key: your-key-here" https://api.example.com/data |
Useful Flags Reference
| Flag | Short | What It Does |
|---|---|---|
--header | -H | Set a request header |
--data | -d | Send request body (implies POST) |
--request | -X | Set HTTP method |
--output | -o | Write response to a file |
--silent | -s | Suppress progress bar |
--verbose | -v | Show full request/response headers |
--include | -i | Include response headers in output |
--location | -L | Follow redirects |
--fail | -f | Return exit code 22 on HTTP errors |
--max-time | -m | Timeout in seconds |
Debugging & Inspecting
See what's actually being sent/receivedbash
| 1 | # Show response headers + body |
| 2 | curl -i https://api.example.com/health |
| 3 | |
| 4 | # Full verbose output (request + response headers, TLS handshake) |
| 5 | curl -v https://api.example.com/health |
| 6 | |
| 7 | # Only the HTTP status code |
| 8 | curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health |
| 9 | |
| 10 | # Response time breakdown |
| 11 | curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://api.example.com/health |
The -w (write-out) flag is incredibly powerful for scripting. See all available variables with man curl or the curl write-out docs.
File Upload & Download
Upload and download patternsbash
| 1 | # Upload a file via multipart form |
| 2 | curl -X POST https://api.example.com/upload \ |
| 3 | -F "file=@/path/to/document.pdf" \ |
| 4 | -F "description=Quarterly report" |
| 5 | |
| 6 | # Download a file |
| 7 | curl -O https://example.com/archive.tar.gz |
| 8 | |
| 9 | # Download with a custom filename |
| 10 | curl -o myfile.tar.gz https://example.com/archive.tar.gz |
| 11 | |
| 12 | # Resume a partial download |
| 13 | curl -C - -O https://example.com/large-file.iso |
Scripting Patterns
Patterns useful in CI/CD and scriptsbash
| 1 | # Retry on failure (up to 3 times, wait 5s between) |
| 2 | curl --retry 3 --retry-delay 5 https://api.example.com/health |
| 3 | |
| 4 | # Fail the script on HTTP error (useful in CI) |
| 5 | curl -f -s https://api.example.com/health || echo "Health check failed!" |
| 6 | |
| 7 | # POST JSON from a file |
| 8 | curl -X POST https://api.example.com/data \ |
| 9 | -H "Content-Type: application/json" \ |
| 10 | -d @payload.json |
| 11 | |
| 12 | # Loop through an API (simple pagination) |
| 13 | for page in 1 2 3 4 5; do |
| 14 | curl -s "https://api.example.com/items?page=$page" >> all_items.json |
| 15 | done |
Avoid putting secrets directly in curl commands — they'll show up in your shell history and ps output. Use environment variables: curl -H "Authorization: Bearer $TOKEN" ... or load from a file with -H @headers.txt.
If you build cURL commands often, try the cURL Command Builder on this site — it generates the command visually and lets you export to code.