curl API Request Examples: Headers, JSON Bodies, Authentication, and Debugging
curlapishttprestcommand-linedebugging

curl API Request Examples: Headers, JSON Bodies, Authentication, and Debugging

TThe Code Website Editorial Team
2026-11-08
6 min read

Copy-ready curl API examples for JSON, headers, authentication, cookies, redirects, response files, and systematic request debugging.

Use these copy-ready curl API examples to reproduce REST requests, send JSON or form data, add headers and authentication, inspect failures, and save responses for further analysis.

Overview

curl is a practical command-line client for testing HTTP endpoints without first writing application code. A well-formed curl request can help you confirm whether a problem is in the API, the network, the request data, or your application’s request-building logic. It is also useful when creating a small reproduction for a bug report or comparing behavior between development, staging, and production environments.

The basic pattern is:

curl [options] "https://api.example.com/resource"

Most API requests add a method, headers, a body, or authentication. The examples below use placeholder domains, IDs, and tokens. Replace them with values from the API documentation you are testing, and avoid placing real secrets in shell history, screenshots, tickets, or shared scripts.

Common method choices

PurposeTypical methodcurl pattern
Read a resourceGETcurl "URL"
Create a resourcePOSTcurl -X POST ...
Replace a resourcePUTcurl -X PUT ...
Partially update a resourcePATCHcurl -X PATCH ...
Delete a resourceDELETEcurl -X DELETE ...

The API contract, not curl itself, determines which methods and fields are valid. Some endpoints also use a POST request for searches or actions that do not fit a simple resource operation.

Template structure

Start with the smallest request that can answer your question, then add one detail at a time. This makes request debugging easier because you can identify which change introduced a different response.

GET with query parameters

curl --get "https://api.example.com/users" \
  --data-urlencode "status=active" \
  --data-urlencode "page=2" \
  --data-urlencode "limit=25"

--get places the data options in the query string instead of sending them as a request body. --data-urlencode is useful for spaces, punctuation, and other characters that need URL encoding. For a small, already encoded query, you can write the URL directly:

curl "https://api.example.com/search?q=error%20logs&limit=10"

Headers

curl "https://api.example.com/profile" \
  -H "Accept: application/json" \
  -H "X-Client-Version: 1.0"

Use Accept to express the response format your client can handle. Add other headers only when the API requires them. Header names are commonly written with conventional capitalization, but HTTP header names are generally treated as case-insensitive.

POST with a JSON body

curl "https://api.example.com/orders" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"productId":"SKU-123","quantity":2}'

The Content-Type header tells the server how to interpret the body. Keep the JSON valid: use double quotes for property names and string values, and do not add trailing commas. If the payload is large or reused, place it in a file and send it with --data @payload.json:

curl "https://api.example.com/orders" \
  -X POST \
  -H "Content-Type: application/json" \
  --data @payload.json

Form-encoded and multipart data

For an endpoint expecting URL-encoded form fields, use --data-urlencode:

curl "https://api.example.com/session" \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=demo@example.com" \
  --data-urlencode "password=replace-this-value"

For a file upload or multipart form, use -F:

curl "https://api.example.com/upload" \
  -X POST \
  -F "description=Release notes" \
  -F "file=@release-notes.txt"

How to customize

Bearer-token authorization

A common API authentication pattern is a bearer token in the Authorization header:

curl "https://api.example.com/account" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Replace the placeholder only in a controlled environment. Do not commit tokens to a repository. If you are inspecting a JWT, remember that decoding its claims is not the same as verifying its signature or trusting its contents. See the JWT decoder guide for that distinction and the related JavaScript and Python JWT authentication guide.

Cookies and session-based requests

To send a known cookie explicitly:

curl "https://api.example.com/dashboard" \
  -H "Cookie: session_id=REPLACE_ME"

To save cookies from one response and reuse them later, use a cookie jar:

curl -c cookies.txt "https://api.example.com/login" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"email":"demo@example.com","password":"replace-this-value"}'

curl -b cookies.txt "https://api.example.com/dashboard"

Cookie behavior depends on the server’s session and security configuration. Treat the cookie file as sensitive because it may grant access to the session represented by the cookie.

Redirects, status codes, and response headers

Use -L when you want curl to follow redirects:

curl -L "https://api.example.com/redirecting-endpoint"

Use -i to include response headers in the output, or -w to print selected request metrics after the response:

curl -i "https://api.example.com/health"

curl -sS -o response.json -w "HTTP %{http_code}\nTime %{time_total}s\n" \
  "https://api.example.com/health"

Here, -sS keeps normal progress output quiet while still showing errors, -o writes the response body to a file, and -w prints a compact summary. Saving the body separately makes it easier to inspect with a JSON formatter or compare against another environment.

Examples

Debug a failing request

When the result is unexpected, begin with verbose output:

curl -v "https://api.example.com/items/42" \
  -H "Accept: application/json"

Verbose mode can show connection details, the outgoing request headers, redirects, and response headers. Review the output for the actual URL, method, authorization header, content type, and response status. Before sharing logs, remove tokens, cookies, API keys, personal data, and other sensitive values.

A useful debugging sequence is:

  1. Confirm the hostname, path, and query parameters.
  2. Confirm that the method matches the endpoint documentation.
  3. Check required headers, especially Content-Type and Authorization.
  4. Validate the JSON body independently before sending it.
  5. Compare the status code and response body with the API’s documented error format.
  6. Repeat the same request with the smallest possible payload.

Send a request and inspect formatted JSON

curl -sS "https://api.example.com/items/42" \
  -H "Accept: application/json" \
  -o response.json

cat response.json

If the response is difficult to read, pass it to a local JSON formatter available in your environment, or use the JSON formatter and validator guide to identify malformed JSON and distinguish formatting issues from API errors.

Reproduce an update request

curl "https://api.example.com/users/42" \
  -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"displayName":"Updated name"}'

Use only fields supported by the endpoint. If the API distinguishes between replacement and partial updates, choose PUT or PATCH accordingly. A successful response may contain a body, an empty body, or a status that indicates the next request should retrieve the updated resource; follow the API’s contract rather than assuming one response shape.

When to update

Revisit a curl request whenever the API contract, authentication flow, environment, or debugging objective changes. A request that worked last month can become misleading if an endpoint path, required field, token scope, content type, redirect behavior, or response format changes.

Update your saved examples when:

  • the API introduces a versioned base URL or changes an endpoint path;
  • authentication moves from one credential type to another;
  • request or response fields are renamed, removed, or made mandatory;
  • an integration begins requiring idempotency keys, pagination parameters, or new headers;
  • an environment uses different hosts, certificates, proxies, or configuration values;
  • a previously exposed secret must be rotated or removed from documentation;
  • your team changes how reproducible bug reports or test fixtures are stored.

For repeatable work, keep the endpoint and environment values separate from the request shape. Shell variables can make a local example easier to adapt:

API_BASE="https://api.example.com"
TOKEN="REPLACE_ME"

curl "${API_BASE}/items" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json"

Do not commit a file containing real credentials. For projects that rely on environment configuration, review the Docker Compose environment variables and secrets guide. If the request is part of an automated job, document its schedule and operational assumptions alongside the code; the cron expression reference can help when that job is scheduled.

Finally, save the smallest curl command that reliably reproduces the behavior, record the expected status and response, and redact sensitive values before sharing it. That habit turns a one-off API test into a dependable debugging artifact.

Related Topics

#curl#apis#http#rest#command-line#debugging
T

The Code Website Editorial Team

Developer Resources 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.