curl Command Tutorial: 15 Examples for Testing APIs from the Terminal
curl is the quickest way to poke an API from the terminal, and it's already installed on most machines. Here are 15 curl command examples you'll actually use, from a simple GET to JSON POSTs, auth headers, file uploads and debugging.

On this page
- The basics
- 1. A simple GET request
- 2. Show the response headers too
- 3. Headers only
- 4. Follow redirects
- Sending data
- 5. POST form data
- 6. POST JSON
- 7. JSON from a file
- 8. PUT, PATCH and DELETE
- Authentication
- 9. Bearer token or API key header
- 10. Basic auth
- Files and output
- 11. Upload a file
- 12. Save the response to a file
- Debugging
- 13. See everything with verbose mode
- 14. Time a request
- 15. Set a timeout
- Reading the status code
- Making JSON readable
- Windows notes
- Turning curl into code
- When a visual tool is easier
Every developer eventually needs to check what an API really returns. Is the endpoint up? Is my token being accepted? Why does the app say "bad request"? Before you open a heavy tool or write a test script, there's curl, a small program that's been around since the late 1990s and ships with macOS, most Linux distributions and modern Windows.
This curl command tutorial skips the theory and goes straight to examples you'll use in real work. Copy them, change the URL, and you're testing.
The basics#
1. A simple GET request#
curl https://api.example.com/status
curl fetches the URL and prints the response body. That's the whole command. If you get JSON back, the server is alive and answering.
2. Show the response headers too#
curl -i https://api.example.com/status
The -i flag includes the status line and headers above the body. This is how you see whether you got a 200, a 401 or a 500, and what content type the server sent.
3. Headers only#
curl -I https://example.com
Capital -I sends a HEAD request, which asks for headers without the body. Handy for checking redirects, caching headers or whether a file exists.
4. Follow redirects#
curl -L http://example.com
By default curl doesn't follow redirects. Add -L and it will, which is what you want when a site redirects HTTP to HTTPS or to a "www" address.
Sending data#
5. POST form data#
curl -d "name=Ada&email=ada@example.com" https://api.example.com/signup
-d sends a body and switches the method to POST. Without a content type header, curl labels it as form data, which is what HTML forms send.
6. POST JSON#
curl -H "Content-Type: application/json" \
-d '{"name":"Ada","plan":"pro"}' \
https://api.example.com/users
Most modern APIs want JSON. Forgetting the Content-Type header is one of the most common reasons for a confusing 400 or 415 error.
7. JSON from a file#
curl -H "Content-Type: application/json" -d @payload.json https://api.example.com/users
The @ tells curl to read the body from a file. Much easier than escaping a long JSON string on the command line.
8. PUT, PATCH and DELETE#
curl -X PATCH -H "Content-Type: application/json" -d '{"plan":"basic"}' https://api.example.com/users/42
curl -X DELETE https://api.example.com/users/42
-X sets the method explicitly. You rarely need it for GET or POST, but you do for everything else.
Authentication#
9. Bearer token or API key header#
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/me
curl -H "X-API-Key: YOUR_KEY" https://api.example.com/me
Which header you use depends on the API's docs. Our overview of API authentication methods explains the common schemes.
10. Basic auth#
curl -u username:password https://api.example.com/private
curl encodes the credentials into a Basic auth header for you. Leave off ":password" and curl will prompt for it, which keeps it out of your shell history.
A word of caution: anything you type on the command line can end up in shell history or logs. For real keys, read them from an environment variable, like -H "Authorization: Bearer $API_TOKEN", and see our guide to API key security.
Files and output#
11. Upload a file#
curl -F "file=@invoice.pdf" -F "note=March" https://api.example.com/upload
-F sends multipart form data, the same format a browser uses for file upload forms.
12. Save the response to a file#
curl -o report.pdf https://example.com/report.pdf
curl -O https://example.com/report.pdf
Lowercase -o lets you choose the filename; uppercase -O keeps the server's.
Debugging#
13. See everything with verbose mode#
curl -v https://api.example.com/status
-v prints the full conversation: DNS lookup, TLS handshake, the exact request headers curl sent and everything the server sent back. When a request works in one tool and not another, compare the verbose output.
14. Time a request#
curl -o /dev/null -s -w "connect: %{time_connect}s total: %{time_total}s\n" https://example.com
-w prints timing variables after the request. It's a quick way to see whether slowness comes from connecting or from the server thinking. On Windows, use -o NUL instead of /dev/null.
15. Set a timeout#
curl --max-time 10 https://api.example.com/slow
Stops curl after 10 seconds, so a hanging endpoint doesn't hang your script.
Reading the status code#
When a request fails, the status code from curl -i usually tells you where to look.
- 400 Bad Request: the server didn't like your body. Check the JSON is valid and the field names match the docs.
- 401 Unauthorized: no credentials, or the wrong ones. Check the header name and that the token hasn't expired.
- 403 Forbidden: you're signed in, but not allowed to do this. Often a permissions or plan issue.
- 404 Not Found: wrong URL, wrong ID, or a missing version prefix like /v1.
- 415 Unsupported Media Type: you forgot the Content-Type header.
- 429 Too Many Requests: you've hit a rate limit. Look for a Retry-After header and wait.
- 500 and above: something broke on the server. Not your fault, but worth reporting with the exact request.
Many APIs also return a JSON error body with a message explaining the problem. Read it before guessing. It's often more specific than the status code, and it saves a lot of trial and error.
Making JSON readable#
APIs often return JSON on a single long line. Pipe it into a formatter to read it: jq is popular on Mac and Linux (curl -s URL | jq). Or paste the response into a JSON formatter in your browser, which also points out the exact spot where invalid JSON breaks.
Windows notes#
Windows 10 and 11 include curl.exe. Two gotchas:
- In PowerShell, type curl.exe, not curl. In older PowerShell versions, curl is an alias for Invoke-WebRequest, which takes completely different options.
- In Command Prompt, single quotes don't group text. Wrap JSON in double quotes and escape the inner quotes: -d "{\"name\":\"Ada\"}". Using -d @file.json avoids the problem entirely.
Turning curl into code#
Once a curl command works, you've effectively written the spec for your code: method, URL, headers and body. Most API docs, including those for SMS and WhatsApp APIs, show curl examples first for exactly this reason. Translate the working command into your language's HTTP client and you'll rarely be surprised. Our REST API guide for beginners covers the concepts behind each part.
When a visual tool is easier#
curl is unbeatable for quick checks and scripts. For longer sessions, like exploring a new API, saving requests or showing a colleague what's happening, a visual tester is friendlier. The Tekservix developer tools include an API tester that runs in your browser, plus the JSON formatter, a regex tester and an SQL builder. Use whichever gets you to the answer faster. Plenty of developers keep both open.
Frequently asked questions
What does the curl command do?
curl transfers data to or from a server using a URL. Developers mostly use it to send HTTP requests to websites and APIs and see exactly what comes back, without writing any code.
How do I send JSON with curl?
Use -X POST (optional when you send data), add the header -H 'Content-Type: application/json', and pass the body with -d, for example -d '{"name":"Ada"}'. On Windows Command Prompt, use double quotes outside and escape the inner ones.
Is curl available on Windows?
Yes. Windows 10 and 11 include curl.exe. In PowerShell, type curl.exe rather than curl, because older PowerShell versions treat curl as an alias for a different command.



