Use this curl and jq API testing checklist to send requests, inspect JSON responses, diagnose failures, and turn one-off debugging into a reproducible command-line workflow.
Overview
When an API call fails inside an application, there are several possible causes: an incorrect URL, missing authentication, an unexpected request body, a proxy problem, or a response that the client cannot parse. Testing the same request from the command line helps separate API behavior from application code.
curl handles HTTP requests, headers, redirects, authentication options, timeouts, and response output. jq filters and formats JSON so that you can inspect one field without reading an entire response. Together, they provide a small, scriptable toolkit for API debugging, deployment smoke tests, webhook validation, and repeatable checks against staging or production endpoints.
Before you begin, confirm that both tools are installed:
curl --version
jq --version
Keep tokens out of shell history, shared tickets, screenshots, and committed scripts. Prefer environment variables or a local secret manager, and use a test account where the API supports one.
Checklist by scenario
1. Make a basic GET request
Start with the smallest request that can answer whether the endpoint is reachable and returns valid JSON.
curl --silent --show-error \
--request GET \
"https://api.example.com/v1/items" | jq .
--silent --show-error suppresses the progress meter while preserving curl errors. Piping to jq . formats the response and fails visibly if the body is not valid JSON. If the API returns a large collection, inspect a field or limit the output:
curl --silent --show-error "https://api.example.com/v1/items" \
| jq '.items[] | {id, name, status}'
2. Add authentication and request headers
Bearer-token APIs commonly expect an Authorization header. Store the token in an environment variable rather than placing it directly in a script.
export API_TOKEN='replace-with-a-short-lived-test-token'
curl --silent --show-error \
--header "Authorization: Bearer ${API_TOKEN}" \
--header "Accept: application/json" \
"https://api.example.com/v1/profile" | jq .
For an API key, follow that provider's documented header or query parameter exactly. Header names, token prefixes, and required scopes differ between APIs. Do not assume that a successful login grants permission to every endpoint.
3. Send a JSON request body
Use --data or --data-raw with a content type when creating or updating a resource.
curl --silent --show-error \
--request POST \
--header "Authorization: Bearer ${API_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{"name":"demo","enabled":true}' \
"https://api.example.com/v1/projects" | jq .
For a larger payload, place the JSON in a file. This makes the request easier to review and repeat:
cat > request.json <<'JSON'
{
"name": "demo",
"enabled": true,
"labels": ["smoke-test"]
}
JSON
curl --silent --show-error \
--request POST \
--header "Authorization: Bearer ${API_TOKEN}" \
--header "Content-Type: application/json" \
--data @request.json \
"https://api.example.com/v1/projects" | jq .
4. Inspect status codes and response headers
A formatted body is not enough to diagnose an API call. Add --include to display response headers, or use --write-out to print a compact status summary after the body.
curl --silent --show-error \
--include \
"https://api.example.com/v1/health"
curl --silent --show-error \
--output response.json \
--write-out 'HTTP %{http_code}\nTime %{time_total}s\nType %{content_type}\n' \
"https://api.example.com/v1/health"
jq . response.json
Saving the body separately prevents status information from being mixed into a JSON stream. This is useful in scripts and makes it easier to attach a sanitized response to a bug report.
5. Extract errors from a JSON response
APIs use different error shapes, so first inspect the complete response. Once you know the structure, select the useful fields:
jq '{code, message, request_id, errors}' response.json
For a response such as {"error":{"code":"invalid_request","message":"..."}}, use:
jq '.error | {code, message}' response.json
Use the optional operator when a field may not exist:
jq '.error?.message // "No API error message returned"' response.json
6. Test pagination
Do not assume that the first response contains every record. Look for fields such as a cursor, next URL, page number, or total count in the API's documentation and response.
curl --silent --show-error \
--header "Authorization: Bearer ${API_TOKEN}" \
"https://api.example.com/v1/items?limit=50" \
| jq '{count: (.items | length), next: .next_cursor}'
Cursor-based APIs often require the returned cursor to be sent in a subsequent request. Treat cursors as opaque values: pass them back without modifying or decoding them unless the API explicitly instructs you to do so.
7. Add bounded retries and timeouts
Retries can help with temporary network failures, but they should be bounded and used carefully for non-idempotent operations. A safe starting point for a read-only request is:
curl --silent --show-error \
--connect-timeout 5 \
--max-time 30 \
--retry 3 \
--retry-delay 2 \
--retry-all-errors \
"https://api.example.com/v1/health" | jq .
Check the curl version and its local help before relying on less common options. For POST requests that create resources, confirm whether the API supports idempotency keys or whether retrying could create duplicates.
8. Save a reproducible smoke test
A smoke test should validate the behavior that matters, not merely that a server returned a response. For example:
set -eu
: "${API_TOKEN:?Set API_TOKEN before running this test}"
body="$(curl --silent --show-error \
--fail-with-body \
--header "Authorization: Bearer ${API_TOKEN}" \
--header "Accept: application/json" \
"https://api.example.com/v1/health")"
printf '%s\n' "$body" | jq -e '.status == "ok"' > /dev/null
printf 'Health check passed\n'
jq -e returns a failing exit status when the expression is false or missing, allowing a CI job or deployment script to stop. Adjust the assertion to match the API's documented response rather than a guessed field.
Command reference
| Option or command | Purpose |
|---|---|
--header | Add an HTTP request header. |
--data @file.json | Send a request body from a file. |
--include | Show response headers with the body. |
--write-out | Print status, timing, or content metadata. |
--fail-with-body | Return a failure status for HTTP errors while retaining the response body. |
jq '.' | Pretty-print JSON. |
jq '.items[]' | Iterate through an array. |
jq -e | Use a filter's result as a script exit status. |
What to double-check
- URL and method: Verify the hostname, API version, path, query parameters, and HTTP method. A valid server with an incorrect path can still return a misleading error.
- Authentication scope: Check whether the token is expired, intended for the correct environment, and authorized for the requested resource.
- Headers: Distinguish
Accept, which describes the response format you want, fromContent-Type, which describes the body you are sending. - JSON types: JSON booleans are
trueandfalse, not quoted strings. Numbers, null values, arrays, and objects may also be validated strictly by the API. - Response status: Check the HTTP status before treating a body as a successful result. A JSON body can describe an error even when the request reached the server.
- Request identifiers: Record a provider's request or correlation ID, but remove tokens, personal data, and confidential payloads before sharing logs.
- Environment differences: Confirm whether you are testing local, staging, or production DNS, certificates, proxies, and credentials. Deployment-related API failures may involve infrastructure rather than application code.
If an API call is part of a release workflow, pair the command-line test with a deployment checklist. Plkdt's CI/CD deployment troubleshooting matrix covers related failures involving builds, secrets, artifacts, and rollbacks. For an endpoint behind Nginx, the Nginx reverse proxy setup guide provides complementary checks for routing, HTTPS, headers, and health checks.
Common mistakes
Treating any response as success
Without --fail-with-body, curl may complete successfully at the transport level even when the server returns an HTTP error. Always inspect the status code or use an explicit assertion.
Putting secrets in command history
Inline tokens can remain in shell history or process listings. Use environment variables, read-only test credentials, and short-lived tokens. Clear sensitive variables when a session ends.
Parsing non-JSON output with jq
HTML from a proxy, plain-text gateway error, or empty response will cause jq to report a parse error. Save headers and the raw body first, then inspect the content type and status.
Copying shell syntax between environments
Quoting, environment variables, and command substitution vary between POSIX shells, PowerShell, and command prompt. Test examples in the shell used by your team, and avoid relying on Bash-only features when portability matters.
Retrying unsafe operations
A retry is not automatically safe. Repeating a create, charge, delete, or webhook action can have side effects. Use retries primarily for reads, or follow the API's documented idempotency mechanism.
When to revisit
Keep this checklist beside your API integration and revisit it whenever the workflow or its inputs change. Review it before a deployment that introduces a new endpoint, authentication scheme, proxy, DNS route, or webhook. Re-run the smoke test after rotating credentials, changing request schemas, upgrading curl or jq, or moving between staging and production.
Refresh saved commands when the API version, response shape, pagination model, or rate-limit behavior changes. A useful maintenance review should confirm that:
- Test credentials still have the minimum required permissions.
- Assertions match the current documented response rather than incidental fields.
- Timeouts and retries fit the operation's side-effect risk.
- Logs do not expose tokens or unnecessary personal data.
- Commands run in the shell and CI environment where they are maintained.
For a practical next step, choose one endpoint your team depends on, save a sanitized request body, record the expected status and JSON field, and turn that check into a small script. Run it manually first, then include it in the appropriate deployment or monitoring workflow. This creates a repeatable baseline for troubleshooting instead of relying on ad hoc browser requests or application logs alone.