When an API request fails, cURL gives you a small, repeatable way to inspect what was sent, what came back, and where the exchange broke down. This guide provides a practical cURL API debugging workflow covering request bodies, headers, authentication, redirects, cookies, TLS, timing, proxies, response files, and safe reproduction.
Overview
cURL is most useful for debugging when you treat a request as a set of independently testable parts: method, URL, headers, authentication, body, transport security, and response handling. Start with the smallest request that should work, then add one variable at a time. This makes it easier to distinguish an application error from a malformed payload, missing header, redirect, certificate problem, or shell-escaping mistake.
Before copying a command into a ticket or chat, remove or replace secrets. Use placeholders such as $API_TOKEN, $SESSION_COOKIE, and https://api.example.test. If you are investigating a contract or payload problem, a JSON Schema workflow can help verify the body separately; see the JSON Schema validation guide.
Check the installed version and supported features before relying on a platform-specific option:
curl --version
For repeatable work, save commands in a temporary script or shell history file with restricted permissions, and avoid placing tokens directly in shared command output.
Checklist by scenario
1. Reproduce a basic GET request
Use --request GET when you want the method to be explicit. For a simple response, this is enough:
curl --request GET \
'https://api.example.test/v1/items?limit=10'
To include response headers in the terminal, add --include:
curl --include --request GET \
'https://api.example.test/v1/items?limit=10'
Headers often reveal the status code, content type, cache behavior, request identifier, and redirect location. Treat request identifiers as useful evidence when asking a service owner to locate a server-side log.
2. Send JSON with the correct headers
A JSON body normally needs both a body option and a content-type header. Use a quoted body for a short example:
curl --request POST \
'https://api.example.test/v1/items' \
--header 'Content-Type: application/json' \
--data '{"name":"Example item","enabled":true}'
For a larger or reusable payload, put the JSON in a file. This avoids shell quoting problems and makes it easier to validate or review:
curl --request POST \
'https://api.example.test/v1/items' \
--header 'Content-Type: application/json' \
--data @payload.json
Do not assume that a successful TCP connection means the body was accepted. Inspect the HTTP status and response body, and compare the exact field names and data types with the API contract.
3. Add bearer-token authentication
Keep the token outside the command where possible. An environment variable reduces accidental exposure in scripts and copied examples:
export API_TOKEN='replace-with-a-short-lived-token'
curl --request GET \
'https://api.example.test/v1/profile' \
--header "Authorization: Bearer $API_TOKEN"
Use a temporary, least-privileged credential for debugging. Never paste a live token into an issue, terminal recording, screenshot, or public code sample. If the API uses a different authentication scheme, reproduce its exact header or parameter rather than adding a bearer header by habit.
4. Test cookies and browser-style sessions
Some endpoints depend on a session cookie rather than an authorization header. Supply only the cookie needed for the test:
curl --request GET \
'https://api.example.test/account' \
--cookie 'session=replace-with-redacted-value'
When a browser request works but cURL does not, compare cookies, origin-related headers, content type, and the request body. Browser behavior can also include a preflight request; the CORS debugging guide covers that separate browser security layer.
5. Upload a multipart form
Use --form for file uploads or multipart fields. cURL constructs the multipart boundary for you:
curl --request POST \
'https://api.example.test/v1/uploads' \
--header "Authorization: Bearer $API_TOKEN" \
--form 'description=Test upload' \
--form 'file=@./example.txt'
Do not manually set a multipart content type with a guessed boundary. A mismatched boundary can make a valid-looking upload unreadable to the server.
6. Inspect headers, redirects, and TLS
For detailed request and connection diagnostics, use verbose mode:
curl --verbose \
--request GET \
'https://api.example.test/v1/health'
Verbose output can include sensitive headers, cookies, and connection details. Redact it before sharing. To follow HTTP redirects, add --location:
curl --location --include \
'https://api.example.test/old-path'
First test without --location so you can see the original status and Location header. Then follow the redirect deliberately. A redirect may change the host, path, or authentication context, so do not assume the final request is equivalent to the original one.
For certificate or TLS investigation, start with verbose output:
curl --verbose \
'https://api.example.test/v1/health'
Avoid using --insecure as a fix. If it is used temporarily to isolate whether certificate verification is involved, record that it changes the security check and do not use it in production automation. For a broader certificate workflow, see SSL certificate errors explained.
7. Measure timing and save the response
Timing data helps separate DNS, connection, TLS, server processing, and transfer delays:
curl --silent --show-error \
--output response.json \
--write-out 'status=%{http_code}\ntime=%{time_total}s\nsize=%{size_download} bytes\n' \
'https://api.example.test/v1/items'
Saving the response preserves evidence without mixing it with progress output. Store the file somewhere access-controlled if it may contain personal, operational, or authentication-related data. For proxy-specific testing, use an explicit proxy:
curl --proxy 'http://proxy.example.test:8080' \
'https://api.example.test/v1/health'
Confirm that the proxy is approved for the data being sent and that your test is actually taking the intended network path.
8. Convert a browser request into cURL
Browser developer tools can often copy a request as cURL. Treat the result as a starting point, not a clean final command. Remove analytics headers, browser-only values, expired cookies, and unnecessary client hints. Keep the method, URL, meaningful headers, body, and authentication mechanism. Then replay the simplified request and add details back only when the behavior changes.
What to double-check
| cURL option or response | Debugging use |
|---|---|
--include | Show response headers alongside the body. |
--verbose | Inspect connection, TLS, request, and response details; redact output before sharing. |
--location | Follow redirects after checking the original redirect response. |
--header | Add content type, authorization, correlation, or conditional headers. |
--data / --data @file | Send a request body, preferably from a file for complex JSON. |
--form | Send multipart fields and files. |
--output | Save a response separately from diagnostic output. |
--write-out | Print selected status, timing, and transfer metrics. |
--cookie | Reproduce cookie-based sessions; protect the cookie value. |
| 2xx | The server accepted the request at the HTTP layer; still validate the response content. |
| 3xx | Inspect the Location header, then decide whether to follow it. |
| 4xx | Check URL, method, authentication, authorization, headers, and body. |
| 5xx | Check server logs, request identifiers, upstream dependencies, and whether the same failure is reproducible. |
Common mistakes
- Copying secrets into shared output: verbose mode and browser-exported commands may expose tokens and cookies. Replace values before sharing.
- Using the wrong shell syntax: quoting and line continuation differ between shells. Test the command in the shell where it will run, and use a payload file when quoting becomes difficult.
- Assuming headers are cosmetic:
Content-Type,Accept, authorization, and conditional headers can change server behavior. - Following redirects blindly: inspect the first response and confirm that the destination is expected.
- Disabling TLS verification permanently:
--insecurecan hide the real certificate or trust problem and weakens the test. - Reading only the status code: an HTTP success response can still contain an application-level error, incomplete data, or an unexpected content type.
- Changing too many variables at once: establish a minimal working request, then compare one difference at a time against the browser, application, or CI request.
For a wider comparison of command-line clients, browser workflows, and other API testing options, review the API testing tools guide. For incoming requests rather than outgoing API calls, the webhook testing guide uses a related inspect-and-replay approach.
When to revisit
Return to this checklist whenever an endpoint behaves differently in a browser, application, CI job, and terminal; when a certificate, proxy, domain, or redirect changes; or when an incident requires a reliable reproduction. Recheck the cURL version and supported options when moving commands between operating systems or build environments.
Before filing a bug, capture a sanitized command, timestamp, environment, HTTP status, relevant response headers, redacted response body, and request identifier. Record whether redirects were followed, whether TLS verification was enabled, and whether a proxy was used. Revisit the command after API authentication, payload, or deployment workflows change. A compact, secret-free reproduction is usually more valuable than a long terminal transcript.
- Start with the smallest request that should succeed.
- Add the required headers and body, validating the payload separately.
- Use
--includeor--verboseto locate the failing layer. - Measure timing and save the response when performance or evidence matters.
- Redact credentials and sensitive data before sharing the result.