curl API Testing Recipes: Headers, Authentication, JSON Payloads, File Uploads, and Repeatable Debug Workflows
curlAPIsHTTPCommand LineJSONTesting

curl API Testing Recipes: Headers, Authentication, JSON Payloads, File Uploads, and Repeatable Debug Workflows

CCodeNScripts Editorial Team
2026-11-16
7 min read

Copy-ready curl recipes for API headers, auth, JSON, uploads, debugging, timeouts, and safe repeatable checks.

Testing an API with curl is fastest when each request is explicit, repeatable, and safe to share. This practical reference covers curl API testing examples for query parameters, headers, authentication, JSON payloads, file uploads, redirects, timeouts, response inspection, and turning successful debugging commands into regression checks without exposing credentials.

Overview

curl is a command-line HTTP client available on many developer systems. It is useful for checking whether an endpoint is reachable, confirming the exact request sent by an application, reproducing a production issue, and comparing behavior across environments. Unlike a browser-based API client, a curl command can be copied into documentation, attached to a bug report, or used as the starting point for a shell-based check.

A reliable curl request should make the important parts visible:

  • The HTTP method and URL.
  • Query parameters and request headers.
  • The authentication method, supplied safely.
  • The request body or uploaded file.
  • Useful output such as status, headers, and response timing.

The examples below use https://api.example.test and placeholder values. Replace them with an endpoint you are authorized to test. Avoid placing real production credentials directly in shell history, source control, tickets, or shared terminal recordings.

How to compare options

When choosing curl flags, start with the question you need to answer rather than adding options by habit. A connectivity check needs less information than a request intended to reproduce an application bug. The following comparison is a practical starting point.

NeedUseful optionWhat it does
Choose a method-XSets a method such as POST or PATCH. Prefer method-aware options such as -d where they already imply the correct method.
Send a header-HAdds a request header, such as Accept or Content-Type.
Send form or JSON data-dSends a request body. Multiple uses can append data depending on the request style.
Upload a file as a form part-FBuilds a multipart form request, commonly used for file uploads.
Show response headers-iIncludes response headers in the output.
Show request and response details-vPrints verbose connection and protocol information. Do not share output without reviewing secrets.
Follow redirects-LFollows HTTP redirects when the endpoint or test requires it.
Set a maximum wait--connect-timeout and --max-timeSeparates connection waiting from the total request limit.
Write only the body-sSSuppresses the progress meter while retaining useful errors.

For repeatable testing, prefer a small command with only the flags that explain the test. Add verbose output temporarily when diagnosing transport, TLS, redirects, or header problems. For response content, pipe JSON into a local formatter or inspect it with a JSON-aware command-line utility rather than relying on unstructured terminal output.

Feature-by-feature breakdown

GET requests and query parameters

A basic GET request is:

curl --request GET "https://api.example.test/users?role=admin&limit=20" \
  --header "Accept: application/json"

Quote the complete URL so shell characters are not interpreted unexpectedly. For parameters containing spaces, ampersands, or other reserved characters, use a properly encoded value. A URL encoder/decoder can help inspect the final query string, but always confirm that encoding matches the API contract.

Headers and content negotiation

Headers often determine how an API interprets a request and formats its response:

curl "https://api.example.test/profile" \
  --header "Accept: application/json" \
  --header "X-Request-ID: local-debug-001"

Use Accept to describe the response format you want and Content-Type to describe the body you are sending. A request ID can make server-side logs easier to correlate, provided your API supports that convention.

Bearer token authentication

A common curl bearer token example uses an environment variable instead of putting the token directly in the command:

export API_TOKEN='replace-with-a-short-lived-token'

curl --request GET "https://api.example.test/orders" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${API_TOKEN}"

Environment variables reduce accidental commits, but they are not a complete secret-management system. Check shell history, process visibility, CI logs, and copied terminal output according to your environment. If a token has been exposed, revoke or rotate it using the process provided by the service.

Basic authentication

For an endpoint that explicitly requires HTTP Basic authentication, use -u and let curl prompt for the password:

curl --user "api-user" \
  --header "Accept: application/json" \
  "https://api.example.test/account"

When prompted, enter the password rather than placing it in the command. Basic authentication must be used with an appropriately protected connection, and it should match the server's documented authentication requirements.

POST JSON requests

This curl POST JSON request sends a small object:

curl --request POST "https://api.example.test/tickets" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"title":"Login issue","priority":"normal"}'

Single quotes work in many Unix-like shells and keep JSON double quotes intact. Windows PowerShell has different quoting behavior, so test the equivalent command in the shell where it will run. For a larger body, use a file to make the payload easier to review:

curl --request POST "https://api.example.test/tickets" \
  --header "Content-Type: application/json" \
  --data @ticket.json

Validate the JSON before sending it. If the endpoint uses a schema, validation can distinguish malformed JSON from a structurally invalid request. See the JSON Schema validation guide for a reusable approach in JavaScript and Python.

PATCH, PUT, and DELETE requests

Use the method required by the API contract and keep the body explicit:

curl --request PATCH "https://api.example.test/users/42" \
  --header "Content-Type: application/json" \
  --data '{"displayName":"Updated name"}'

curl --request DELETE "https://api.example.test/users/42" \
  --header "Accept: application/json"

Be cautious when testing mutating methods against shared or production data. Prefer a disposable record, a non-production environment, or a documented dry-run capability.

Multipart file uploads

Use -F when an endpoint expects multipart/form-data:

curl --request POST "https://api.example.test/documents" \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --form "description=Test document" \
  --form "file=@./sample.pdf;type=application/pdf"

Do not manually set the multipart Content-Type header unless you also manage its boundary correctly; curl constructs the form boundary for you. Confirm file size, extension, detected type, and server-side validation separately. The secure file uploads checklist covers validation and storage concerns that a curl command cannot solve.

Redirects, timeouts, and response inspection

For a redirect-aware request with a bounded runtime:

curl --location "https://api.example.test/health" \
  --connect-timeout 5 \
  --max-time 20 \
  --silent --show-error \
  --include

--include displays response headers alongside the body. Use --verbose when you need connection details:

curl --verbose "https://api.example.test/health"

Review verbose output before sharing it because URLs, authorization details, cookies, or other sensitive values may appear. To inspect timing without dumping a large body, combine output handling with a format such as:

curl --silent --output /dev/null \
  --write-out "status=%{http_code} total=%{time_total}s\n" \
  "https://api.example.test/health"

Best fit by scenario

  • Checking reachability: Use a simple GET with --connect-timeout, --max-time, and --write-out. This answers whether the endpoint responds within an expected boundary.
  • Reproducing an application bug: Match the application's method, URL, headers, body, and authentication as closely as possible. Start with --verbose only when the normal request does not explain the failure.
  • Testing an API contract: Store a sanitized JSON body and check the status code and response shape. OpenAPI validation and contract testing can provide broader protection against API drift.
  • Investigating rate limits: Record the status, relevant response headers, and timing without repeatedly hammering the endpoint. For retry behavior, use the principles in the HTTP 429 handling guide.
  • Comparing environments: Keep the command structure identical while changing only the base URL and injected credentials. This makes differences in headers, status codes, or response bodies easier to isolate.
  • Creating a repeatable check: Put the sanitized command in a script, fail on unexpected status codes, and keep secrets in the CI system's protected variables. A successful manual command is a starting point, not automatically a complete test.

For a basic shell check, capture the HTTP status explicitly:

status=$(curl --silent --output response.json \
  --write-out "%{http_code}" \
  --header "Accept: application/json" \
  "https://api.example.test/health")

if [ "$status" != "200" ]; then
  echo "Unexpected HTTP status: $status" >&2
  exit 1
fi

Adapt status expectations to the endpoint. For example, creation, deletion, authentication failure, and asynchronous processing may have different valid responses. Avoid asserting only that curl completed: a transport success can still contain an HTTP error response.

When to revisit

Revisit this curl API testing reference whenever an API contract changes, an authentication method is replaced, a file-upload field is renamed, or a request behaves differently between environments. It is also worth reviewing your commands when a shell or CI runner changes, because quoting, environment-variable expansion, certificate configuration, and path syntax can differ.

Before committing a curl-based check, use this short review:

  1. Confirm the URL, method, headers, body format, and expected status with the API contract.
  2. Replace embedded credentials with environment variables or the CI platform's secret store.
  3. Sanitize tokens, cookies, personal data, and internal hostnames from saved examples and logs.
  4. Set connection and total-time limits so a broken endpoint cannot hang the workflow indefinitely.
  5. Check both the HTTP status and the response body or schema relevant to the test.
  6. Run the command against a safe environment before using it against shared data.

Keep the final command close to the bug report, API documentation, or automated test that depends on it. That small maintenance habit turns one-off curl debugging into a reusable code snippet that remains useful when endpoints, payloads, and environments evolve.

Related Topics

#curl#APIs#HTTP#Command Line#JSON#Testing
C

CodeNScripts Editorial Team

Technical 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.