cURL API Debugging Guide: Inspect Headers, Authentication, Redirects, TLS, and Request Bodies
cURLAPI debuggingHTTPcommand lineTLSdeveloper productivity

cURL API Debugging Guide: Inspect Headers, Authentication, Redirects, TLS, and Request Bodies

TTecksite Editorial Team
2026-11-21
7 min read

A practical cURL API debugging checklist for reproducing requests, inspecting headers, auth, redirects, TLS, bodies, timing, and errors safely.

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 responseDebugging use
--includeShow response headers alongside the body.
--verboseInspect connection, TLS, request, and response details; redact output before sharing.
--locationFollow redirects after checking the original redirect response.
--headerAdd content type, authorization, correlation, or conditional headers.
--data / --data @fileSend a request body, preferably from a file for complex JSON.
--formSend multipart fields and files.
--outputSave a response separately from diagnostic output.
--write-outPrint selected status, timing, and transfer metrics.
--cookieReproduce cookie-based sessions; protect the cookie value.
2xxThe server accepted the request at the HTTP layer; still validate the response content.
3xxInspect the Location header, then decide whether to follow it.
4xxCheck URL, method, authentication, authorization, headers, and body.
5xxCheck 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: --insecure can 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.

  1. Start with the smallest request that should succeed.
  2. Add the required headers and body, validating the payload separately.
  3. Use --include or --verbose to locate the failing layer.
  4. Measure timing and save the response when performance or evidence matters.
  5. Redact credentials and sensitive data before sharing the result.

Related Topics

#cURL#API debugging#HTTP#command line#TLS#developer productivity
T

Tecksite Editorial Team

Developer Tools Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.