cURL turns API testing into a repeatable command-line workflow: you can send the same request, inspect the complete response, compare authentication attempts, and save a working example for scripts or deployment checks. This guide provides reusable cURL templates for common REST API scenarios, explains the options that matter most, and gives you a practical checklist for finding why a request fails.
Overview
To test a REST API with cURL, describe four things clearly: the request URL, the HTTP method, the headers, and the request body. Start with the smallest valid request, then add authentication, content negotiation, query parameters, or a payload one piece at a time. This makes failures easier to isolate than copying a large command and changing several variables at once.
A basic GET request looks like this:
curl "https://api.example.test/v1/items"
For useful diagnostics, add silent mode with errors, response headers, or verbose connection details:
curl -sS -i "https://api.example.test/v1/items"
curl -sS -v "https://api.example.test/v1/items"
| Option | Purpose | Use it when |
|---|---|---|
-X | Sets the HTTP method | You need a method that is not inferred from the request body |
-H | Adds a request header | You need authorization, content type, or an accept preference |
-d | Sends request data | You are submitting JSON, form data, or another payload |
-i | Includes response headers in the output | You need to inspect status, redirects, cookies, or server headers |
-v | Shows verbose request and connection details | You are debugging TLS, redirects, headers, or connection behavior |
-L | Follows redirects | The endpoint intentionally redirects and you need the final response |
-o | Writes the response body to a file | The body is large, binary, or easier to inspect separately |
-w | Prints selected transfer information | You want a compact status code or timing result for a check |
Use -i when you want headers and the body together. Use -v when you need to understand what cURL sent and how the connection behaved. Verbose output can contain sensitive request details, so avoid pasting it into public issue trackers without reviewing it.
Checklist by scenario
1. Test a simple GET endpoint
Begin with the URL exactly as documented. Quote the entire URL, especially when it contains query parameters, ampersands, spaces, or characters interpreted by your shell.
curl -sS -i "https://api.example.test/v1/search?q=tools&limit=10"
Confirm the status line, content type, response body, and any pagination or cache headers. If the endpoint returns JSON, you can save the body and inspect it with a JSON formatter or validator such as the JSON Formatter and Validator Guide.
2. Send JSON with a POST request
For a JSON API, provide both the method and the content type. The --data option sends the body; many API clients use POST when this option is present, but specifying -X POST makes the intended request explicit in a reusable test.
curl -sS -i -X POST "https://api.example.test/v1/items" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data '{"name":"Example item","enabled":true}'
Keep the JSON valid and make sure the field names match the API contract. If the shell treats quotation marks differently, place the payload in a file:
curl -sS -i -X POST "https://api.example.test/v1/items" \
-H "Content-Type: application/json" \
--data @payload.json
3. Add a bearer token
A common authorization pattern sends a token in the Authorization header:
curl -sS -i "https://api.example.test/v1/profile" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
Do not commit real tokens in shell history, source code, screenshots, or shared documentation. For local testing, use an environment variable and quote its expansion:
export API_TOKEN='replace-with-a-short-lived-token'
curl -sS -i "https://api.example.test/v1/profile" \
-H "Authorization: Bearer ${API_TOKEN}"
When investigating a token, distinguish between reading its claims and proving that it is valid. A JWT decoder and debugging guide can help you inspect claims such as expiration, but decoding a token does not verify its signature or grant access.
4. Submit multipart form data or a file
Use -F for a multipart form request. This is suitable for endpoints that accept file uploads and ordinary form fields.
curl -sS -i -X POST "https://api.example.test/v1/uploads" \
-F "description=Release artifact" \
-F "file=@./build.zip"
Do not manually add a multipart content type unless the API specifically requires it; cURL needs to construct the boundary that separates each part.
5. Inspect redirects and response headers
First see whether the endpoint returns a redirect without following it:
curl -sS -i "https://api.example.test/old-path"
Then follow redirects when that is the behavior you want to test:
curl -sS -i -L "https://api.example.test/old-path"
Compare the original and final URLs, status codes, location headers, and whether authentication is expected to survive the redirect. Treat redirects across hosts carefully and do not assume that every client handles credentials in the same way.
6. Reproduce a browser request
Browser developer tools commonly offer a “Copy as cURL” action. It is useful for reproducing a request, but treat the result as a diagnostic starting point rather than a clean test. Remove cookies, tracking headers, temporary browser metadata, and unnecessary values. Keep only the method, URL, required headers, body, and authentication needed to reproduce the behavior.
What to double-check
- URL encoding: Quote URLs in the shell. Encode query values when they contain reserved characters, and check whether the API expects repeated parameters, commas, or a JSON-encoded value.
- HTTP method: Verify that the endpoint expects GET, POST, PUT, PATCH, or DELETE. A valid URL with the wrong method can produce a misleading 404, 405, or validation error.
- Headers: Separate authentication from content negotiation.
Authorization,Content-Type, andAcceptserve different purposes. Check spelling and capitalization of custom headers required by the API. - Payload format: A JSON body needs valid JSON and usually a matching content type. Form-encoded, multipart, and raw text bodies are not interchangeable.
- Status versus body: Read the HTTP status before interpreting the response body. A successful transport does not necessarily mean the application accepted the request.
- Authentication context: Check whether the token is expired, scoped for the requested resource, issued for the correct environment, or missing a required prefix such as
Bearer. - Environment: Confirm the hostname, port, API version, and deployment environment. Testing a staging token against a production host can look like an authentication failure.
- Network details: If the request fails before an HTTP response, use
-vand check DNS, TLS, proxy, firewall, and certificate behavior separately from API logic.
For compact smoke tests, you can print the status code after the response:
curl -sS -o /tmp/api-response.json \
-w "HTTP %{http_code}\n" \
"https://api.example.test/health"
Keep the saved response available when debugging. It can show an error identifier, request ID, or validation detail that is easy to miss in terminal output.
Common mistakes
- Leaving the URL unquoted: Shells can interpret ampersands and other characters before cURL receives them. Quote the URL as a default habit.
- Using the wrong shell syntax: Single-quoted JSON examples work naturally in many Unix-like shells. PowerShell uses different quoting and variable expansion rules, so test the command in the shell where it will actually run.
- Adding JSON without declaring it: Sending a body does not guarantee that the server will parse it as JSON. Include
Content-Type: application/jsonwhen the API expects it. - Hiding the response status: A command that prints only a body can make a redirect, authorization failure, or server error look ambiguous. Use
-ior-wduring investigation. - Assuming verbose output is safe to share: Headers, cookies, URLs, and tokens may appear in diagnostics. Redact secrets before sharing logs.
- Copying browser state into automation: Browser cookies and temporary headers can make a copied command work once and fail later. Reduce the request to its actual contract.
- Testing only the happy path: Add checks for missing fields, invalid tokens, expired credentials, unsupported methods, and malformed JSON where those cases matter to the integration.
If you generate checksums for downloaded responses or release artifacts, compare the expected algorithm and input bytes carefully. The Hash Generator Guide covers the distinction between hashing text and verifying files.
When to revisit
Return to this checklist whenever an endpoint, authentication flow, deployment environment, or shell script changes. It is especially useful before a release, after an API version upgrade, when a token provider changes, or when a webhook or integration begins returning a different status code.
Keep one minimal cURL command for each important endpoint and store request bodies as separate fixture files where practical. Review those examples during seasonal planning cycles and before deployment automation is updated. Remove expired credentials, replace environment-specific hosts with clearly named variables, and confirm that the command still reflects the current API contract.
For the next failure, follow this order:
- Run the smallest request that should work.
- Add
-ito inspect the status and headers. - Add
-vonly when connection or request details are necessary. - Verify the URL, method, headers, body, and environment one at a time.
- Save the response and redact secrets before sharing the reproduction.
- Turn the confirmed command into a repeatable smoke test or regression fixture.
This process keeps cURL API testing useful beyond one-off debugging: the same request can become a documented example, a deployment check, or a precise reproduction for an API issue.