curl REST API Examples: Authentication, JSON Requests, Uploads, and Troubleshooting

Overview

curl is useful for API testing because it makes the complete HTTP request visible and easy to reproduce. Unlike a browser address bar, a curl command can include request methods, authentication headers, JSON bodies, multipart files, timeout limits, and response output in a script or terminal history. That makes it practical for debugging a new endpoint, verifying a deployment, comparing environments, or capturing a production issue without relying on a graphical client.

Replace https://api.example.com/v1/users and the sample values below with your endpoint and test data. The examples use a Unix-like shell. Windows PowerShell supports curl commands too, but quoting and the meaning of the curl command can vary by installation, so verify the syntax in your local environment.

For a broader comparison of command-line and graphical API debugging workflows, see API Debugging Tools Compared. When a response contains JSON, a JSON formatter and validator can make nested data easier to inspect.

What to track

Basic GET requests

A GET request is the simplest way to check whether an endpoint responds and whether its status code and payload look correct.

curl https://api.example.com/v1/users

Add --include (or -i) to display response headers with the body:

curl --include https://api.example.com/v1/users

For a compact diagnostic view, --verbose (or -v) shows connection details, request headers, and response headers. Use it when you need to determine whether a problem occurs during DNS lookup, TLS negotiation, request transmission, or server processing.

curl --verbose https://api.example.com/v1/users

Query parameters and custom headers

Query parameters can be written directly into the URL, but --get with --data-urlencode is safer when values contain spaces or reserved characters.

curl --get https://api.example.com/v1/search \
  --data-urlencode "q=red shoes" \
  --data-urlencode "limit=20"

Custom headers are added with --header (or -H). The following example sends an explicit media type and a request identifier that can help correlate logs:

curl https://api.example.com/v1/orders \
  --header "Accept: application/json" \
  --header "X-Request-ID: local-api-check-001"

POST requests with JSON

To test a JSON API, set the content type and pass the body with --data. The --request POST flag makes the method explicit, although curl generally infers POST when data is supplied.

curl --request POST https://api.example.com/v1/users \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"name":"Ada Lovelace","email":"ada@example.test"}'

For a larger or reusable payload, put the JSON in a file and use --data @payload.json:

curl --request POST https://api.example.com/v1/users \
  --header "Content-Type: application/json" \
  --data @payload.json

Validate and format the file before sending it. This separates JSON syntax errors from API validation errors; a malformed document may never reach the application logic you intended to test.

Bearer and basic authentication

A bearer token is commonly sent in the Authorization header.

curl https://api.example.com/v1/profile \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

Do not commit a real token in source code or paste it into a shared issue. A shell variable keeps the command easier to reuse, although you should still consider shell history and process visibility:

export API_TOKEN='replace-with-a-short-lived-test-token'
curl https://api.example.com/v1/profile \
  --header "Authorization: Bearer $API_TOKEN"

For HTTP Basic Authentication, use --user (or -u):

curl --user 'username:password' \
  https://api.example.com/v1/account

Prefer a test account with the minimum required permissions. Basic credentials and bearer tokens should be supplied through a secret manager, protected environment, or interactive mechanism where possible.

File uploads

Use --form (or -F) for a multipart form upload. The field name must match the API documentation.

curl --request POST https://api.example.com/v1/files \
  --header "Authorization: Bearer $API_TOKEN" \
  --form "file=@./report.pdf" \
  --form "description=Quarterly report"

Do not manually set the multipart content type unless the API specifically requires it. curl generates the boundary needed to separate form fields and file content.

Useful flags at a glance

Cadence and checkpoints

API checks become more valuable when they are repeatable rather than improvised. Keep a small request checklist for each important endpoint and revisit it monthly or quarterly, depending on how often the API changes.

1. Record the contract. Note the method, URL pattern, required headers, authentication type, expected status code, and a minimal valid body.
2. Check each environment. Run the same request against local, staging, and production-like environments with separate credentials and safe test data.
3. Capture representative responses. Save a successful response and at least one expected validation error. Redact tokens, personal data, and internal identifiers before sharing files.
4. Set explicit limits. Add a connection timeout and an overall maximum time to prevent a diagnostic script from waiting forever.
5. Compare after changes. Re-run the request after deployments, authentication changes, schema migrations, proxy changes, or updates to upstream services.

A simple repeatable check might look like this:

curl --silent --show-error --fail-with-body \
  --connect-timeout 5 \
  --max-time 20 \
  --output response.json \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/v1/health

Use --silent --show-error when scripting so normal progress output stays quiet while errors remain visible. If the response is expected to be JSON, inspect the saved file with a formatter or validator before comparing it with an earlier result.

How to interpret changes

Start with the HTTP status code, then examine headers and the response body. A request can reach the server successfully but still fail application validation, authorization, rate controls, or business rules.

• 2xx responses: Check that the returned representation contains the fields and values your client expects, not merely that the request succeeded.
• 3xx responses: Determine whether a redirect is expected. Test with and without --location; redirect behavior can affect methods, headers, and authentication handling.
• 4xx responses: Compare the method, URL, query encoding, required headers, token scope, and JSON shape. A validation response often identifies the exact field to correct.
• 5xx responses: Re-run with a request ID, a bounded timeout, and verbose output. Compare the result across environments to distinguish an application failure from a proxy, DNS, or TLS issue.
• Timeouts or connection errors: Separate connection time from server processing. Check the hostname, port, certificate trust, network route, and service availability before changing the request body.

For token-specific investigations, decode only non-sensitive test tokens and remember that reading claims is not the same as verifying a token. The JWT decoder and debugging guide covers that distinction. Never paste production secrets into an online utility or a public ticket.

When to revisit

Revisit your curl API examples whenever an endpoint contract or its operating environment changes. A monthly or quarterly review is a useful baseline for stable services, while active APIs may need checks in every deployment workflow.

Update the commands when authentication changes from basic credentials to bearer tokens, token scopes change, a versioned path is retired, required headers are added, or a JSON field becomes mandatory. Recheck upload commands when accepted file types, field names, size limits, or storage behavior change. Review redirect and TLS diagnostics after introducing a new gateway, load balancer, hostname, or certificate configuration.

Before each review, remove expired credentials, confirm that test data is safe, and verify that saved response fixtures do not contain personal or confidential information. Then run the smallest successful request, an intentional validation failure, and any endpoint-specific upload or pagination case. Compare status codes, important headers, response shape, and timing with the previous checkpoint.

Keep the final commands in a private, version-controlled runbook or a protected test script rather than copying secrets into documentation. For related command-line and utility workflows, see Online Developer Utilities Compared. A short, maintained curl checklist turns one-off API debugging into a dependable part of backend development and deployment verification.