cURL Generator Guide: Build API Requests & Debug HTTP Endpoints

cURL Basics — What It Does

cURL (Client URL) is a command-line tool that transfers data to/from servers using URLs. It supports HTTP, HTTPS, FTP, SMTP, and dozens of other protocols. For API development, it's the lowest-level way to make HTTP requests — no SDK, no Postman, no abstraction layer between you and the raw request/response.

# Simplest GET request
curl https://api.example.com/users

# With verbose output (shows headers, TLS, timing)
curl -v https://api.example.com/users

# Save response to file
curl -o response.json https://api.example.com/users

The Most Useful Flags

Authentication Patterns

Bearer token (JWT, OAuth2)

curl -X GET "https://api.example.com/users/me" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Accept: application/json"

API key in header

curl -X GET "https://api.example.com/data" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Basic Authentication

# Let cURL encode the credentials
curl -u "username:password" https://api.example.com/resource

# Or set the header manually (Base64 of "username:password")
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
     https://api.example.com/resource

Use our Base64 Encoder to generate the value for manual Basic Auth headers. For generating strong API keys and secrets, use our Password Generator.

HMAC webhook signature

# Compute signature and include in header
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/.* //')
curl -X POST "https://your-webhook-endpoint.com/events" \
  -H "Content-Type: application/json" \
  -H "X-Signature-256: sha256=$SIGNATURE" \
  -d "$PAYLOAD"

Test webhook signature validation with our Webhook Signature Verifier.

Sending Request Bodies

JSON body (most common)

curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "role": "admin"
  }'

Always set Content-Type: application/json when sending JSON — without it, many APIs reject the body or misparse it. Format and validate your JSON payload first with our JSON Formatter before embedding in the cURL command.

Form data

curl -X POST "https://api.example.com/upload" \
  -F "file=@/path/to/file.pdf" \
  -F "title=My Document" \
  -H "Authorization: Bearer your-token"

URL-encoded form

curl -X POST "https://api.example.com/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=abc&client_secret=xyz"

Use our URL Encoder to properly encode any special characters in form values before embedding them.

Inspecting Response Details

Check HTTP status code only

curl -s -o /dev/null -w "%{http_code}" https://api.example.com/users

Response headers and timing

curl -s -o /dev/null -w "Status: %{http_code}\nTime: %{time_total}s\nSize: %{size_download} bytes\n" \
     https://api.example.com/users

Follow redirects and show final URL

curl -L -w "Final URL: %{url_effective}\n" https://api.example.com/redirect

Reference our HTTP Status Code guide when interpreting response codes — knowing the difference between 401 vs 403 or 422 vs 400 changes how you debug.

Debugging TLS Issues

# Show TLS certificate details
curl -v --head https://api.example.com 2>&1 | grep -A 20 "Server certificate"

# Use specific TLS version
curl --tlsv1.2 https://api.example.com

# Skip verification (only in dev, never production)
curl -k https://localhost:8443/api/test

The -v (verbose) flag shows the full TLS handshake — certificate chain, cipher suite, and protocol version. This is indispensable when debugging MTLS or certificate pinning issues.

Multi-step Flows with Session Cookies

# Step 1: Login and save cookies
curl -X POST "https://app.example.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret"}' \
  -c cookies.txt

# Step 2: Use saved cookies for authenticated request
curl -X GET "https://app.example.com/dashboard" \
  -b cookies.txt

The -c flag saves cookies to a file; -b loads them. This simulates a full browser session for testing cookie-based authentication.

Building Reproducible Bug Reports

A cURL command is the gold standard for reporting API bugs — it removes all ambiguity about what was sent:

# Complete, reproducible bug report command
curl -X POST "https://api.example.com/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: $(uuidgen)" \
  -d '{"productId": "prod_123", "quantity": 0}' \
  -w "\nStatus: %{http_code}" \
  -s

Before sharing: scrub real tokens from the command and replace with $TOKEN or a dummy value. Use our PII Redactor to sanitize any embedded user data in request bodies. Document the failing request alongside expected vs actual behavior in our Markdown Editor for clean issue reports.

Generating UUIDs for Request Tracing

Many APIs benefit from a unique X-Request-ID or X-Trace-ID header for correlating requests across distributed logs:

curl -X POST "https://api.example.com/orders" \
  -H "X-Request-ID: $(uuidgen)" \
  ...

Use our UUID Generator for consistent UUID v4 generation when building test suites or scripting batch API calls.