How to Use cURL to Test APIs — Commands, Examples & Convert to Code

# Basic GET — returns the response body
curl https://api.example.com/users

# GET with pretty-printed JSON output (pipe through python -m json.tool)
curl https://api.example.com/users | python3 -m json.tool

# GET and see response headers too (-i = include headers)
curl -i https://api.example.com/users

# GET and see ONLY the response headers (-I = HEAD request)
curl -I https://api.example.com/users

# GET and save the output to a file (-o = output file)
curl https://api.example.com/users -o users.json

# GET with verbose output — see the full request and response (-v)
curl -v https://api.example.com/users

# POST with inline JSON body
curl -X POST 'https://api.example.com/users'   -H 'Content-Type: application/json'   -H 'Authorization: Bearer TOKEN'   -d '{"name": "Alice", "email": "alice@example.com", "role": "admin"}'

# POST with JSON from a file (@ prefix reads from file)
curl -X POST 'https://api.example.com/users'   -H 'Content-Type: application/json'   -H 'Authorization: Bearer TOKEN'   -d @user-payload.json

# POST with URL-encoded form data (like an HTML form submission)
curl -X POST 'https://api.example.com/login'   -d 'username=alice&password=s3cr3t'

# POST with multipart form data (file upload)
curl -X POST 'https://api.example.com/upload'   -H 'Authorization: Bearer TOKEN'   -F 'file=@/path/to/document.pdf'   -F 'title=Q4 Report'

# Bearer token (most common — OAuth 2.0, JWT)
curl 'https://api.example.com/me'   -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

# HTTP Basic auth — username:password
curl 'https://api.example.com/data' -u 'myuser:mypassword'
# cURL auto-encodes as Base64 and sets Authorization: Basic header

# API key in a header (varies by API — check the docs)
curl 'https://api.example.com/data' -H 'X-API-Key: sk-live-abc123'

# API key in a query string
curl 'https://api.example.com/data?api_key=sk-live-abc123'

# GitHub API example (token in header)
curl 'https://api.github.com/user/repos'   -H 'Authorization: token ghp_yourtoken'   -H 'Accept: application/vnd.github.v3+json'

# OpenAI API example
curl 'https://api.openai.com/v1/models'   -H 'Authorization: Bearer sk-proj-...'

BASE='https://api.example.com'
TOKEN='Bearer TOKEN'

# READ — GET a single resource
curl "$BASE/users/42" -H "Authorization: $TOKEN"

# CREATE — POST a new resource
curl -X POST "$BASE/users"   -H "Content-Type: application/json"   -H "Authorization: $TOKEN"   -d '{"name": "Bob", "email": "bob@example.com"}'

# FULL UPDATE — PUT replaces the entire resource
curl -X PUT "$BASE/users/42"   -H "Content-Type: application/json"   -H "Authorization: $TOKEN"   -d '{"name": "Bob Smith", "email": "bob@example.com", "role": "viewer"}'

# PARTIAL UPDATE — PATCH updates only specified fields
curl -X PATCH "$BASE/users/42"   -H "Content-Type: application/json"   -H "Authorization: $TOKEN"   -d '{"role": "admin"}'

# DELETE
curl -X DELETE "$BASE/users/42" -H "Authorization: $TOKEN"
# Returns 204 No Content on success

# -v (verbose) — see the full request, response headers, TLS handshake
curl -v 'https://api.example.com/data'

# -w (write-out) — time the request breakdown
curl -w "

DNS: %{time_namelookup}s
Connect: %{time_connect}s
TLS: %{time_appconnect}s
Total: %{time_total}s
"   -o /dev/null -s 'https://api.example.com/data'

# -L (follow redirects) — follow 301/302 automatically
curl -L 'https://api.example.com/old-path'

# -k (insecure) — skip SSL cert validation (dev/testing only, never production)
curl -k 'https://localhost:8443/api'

# --retry 3 — retry on connection failure
curl --retry 3 --retry-delay 2 'https://api.example.com/data'

# --limit-rate 100k — throttle download speed (useful for testing)
curl --limit-rate 100k 'https://api.example.com/large-file.json'

# -x (proxy) — route through a proxy server
curl -x 'http://proxy.internal:8080' 'https://api.example.com/data'

# --resolve — test with a specific IP (bypass DNS for one request)
curl --resolve 'api.example.com:443:192.168.1.100' 'https://api.example.com/data'