APITesterCurl is the common language of HTTP APIs: documentation is written in it, bug reports quote it, and support teams ask for it. A curl command is a complete, unambiguous description of a request, which is exactly why a small misunderstanding of one flag produces confusing results. These pages take one task at a time and show the command, what each part contributes, and what the server sees.
Runnable examples point at httpbin.org, a public service that echoes back whatever you send, so
you can see the effect of a flag in the response. If you would rather not use a terminal, the
API Tester sends the same requests from your browser, and the
curl converter turns any command into Python, JavaScript, PHP and more.
Curl commands at a glance
| Task | Command |
|---|---|
| GET Request | curl https://httpbin.org/get |
| POST JSON | curl https://httpbin.org/post -H "Content-Type: application/json" -d '{"name":"Ada","role":"admin"}' |
| POST Form | curl -d "email=ada@example.com" -d "plan=starter" https://httpbin.org/post |
| POST File | curl -F "file=@report.pdf" https://httpbin.org/post |
| Send Header | curl https://httpbin.org/headers -H "X-Request-Id: 7f3a9c" -H "Accept-Language: en-GB" |
| Bearer Token Auth Header | curl -H "Authorization: Bearer $TOKEN" https://httpbin.org/bearer |
| Basic Auth | curl -u ada:s3cret https://httpbin.org/basic-auth/ada/s3cret |
| Follow Redirect | curl -L https://httpbin.org/redirect/2 |
| Download File | curl -fLO https://example.com/files/report.pdf |
| HEAD Request | curl -I https://httpbin.org/get |
| Timeout | curl --connect-timeout 5 --max-time 20 https://httpbin.org/delay/3 |
| Proxy Server | curl -x http://proxy.example.com:8080 https://httpbin.org/ip |
Methods
Curl GET Request Example
GET is what curl does when you give it nothing but a URL.
Curl POST Example
Curl switches to POST the moment you give it a body.
Curl PUT Example
PUT replaces the resource at a URL with the body you send.
Curl PATCH Request Example
PATCH changes part of a resource.
Curl DELETE Request Example
Deleting with curl is one flag.
Curl HEAD Request Example
HEAD asks for the headers a GET would return and nothing else.
Curl OPTIONS Request Example
OPTIONS asks a server what it would accept at a URL.
Request bodies
Curl POST JSON Example
Sending JSON takes two things: the JSON itself and a header saying that is what it is.
Curl GET JSON Example
Fetching JSON is a GET with one header that says what you want back.
Curl POST Form Example
HTML forms post in one of two encodings, and curl has a flag for each.
Curl POST File Example
There are three different things people mean by "post a file", and they are three different requests.
Curl POST XML Example
XML over HTTP works like JSON over HTTP with different media types, plus one extra header if the service speaks SOAP.
Curl -d Flag Example
-d looks like "send this data", but it does three things at once and quietly edits file input.
Curl POST Body Example
The body of a POST can come from four places: the command line, a file, another program's output, or a block of text in your script.
Curl JSON Request Example
A JSON API call has two sides, the JSON you send and the JSON you get back, and each has its own header.
Curl GET XML Example
Fetching XML is a GET with an Accept header.
Headers
Curl Send Header Example
-H adds a header line to the request.
Curl Content-Type Example
Content-Type tells the server how to parse the body you sent.
Curl User Agent Example
Every curl request announces itself as curl.
Curl Send Cookies Example
Curl ignores cookies unless told otherwise.
Curl No Cache Example
Curl keeps no cache of its own, so a stale response always comes from something in between: a CDN, a reverse proxy, a corporate gateway.
Curl Keep-Alive Example
"Keep-alive" names two unrelated mechanisms, and curl has switches for both.
Curl Custom Headers Example
A custom header is one an application defines for itself: an API version, an idempotency key, a tenant, a request id.
Curl Close Connection Header Example
Connection: close asks the other side to hang up once the response is complete.
Authentication
Curl Basic Auth Example
-u takes a username and password and turns them into an Authorization: Basic header.
Curl Bearer Token Auth Header Example
A bearer token is a credential you present in a header; whoever holds it is treated as its owner.
Curl -u Flag Example
-u hands curl a username and a password.
Curl Request With Credentials Example
"Credentials" covers several unrelated mechanisms, and an API accepts exactly the one it was built for.
Curl POST With Basic Authentication Example
A POST with Basic authentication is two separate things in one command: a header that identifies you and a body that carries the data.
HTTPS and TLS
Curl HTTPS Request Example
An https:// URL is all curl needs to use TLS, and it verifies the server's certificate by default.
Curl Ignore Certificate Checks Example
-k tells curl to proceed even though it cannot verify who it is talking to.
Curl -k Flag Example
-k is short for --insecure.
Curl SSL Request Example
Every https:// request curl makes is an SSL request in the everyday sense, although the protocol has been called TLS for a long time.
Network behaviour
Curl Follow Redirect Example
Curl does not follow redirects unless asked.
Curl Timeout Example
By default curl puts no limit on how long a transfer may take, so one silent server can hang a script indefinitely.
Curl Proxy Server Example
-x routes a request through a proxy.
Curl Download File Example
Curl prints what it downloads to the terminal unless told to save it.
Curl CORS Request Example
Curl cannot have a CORS error.
Curl Verbose Example
-v makes curl narrate the whole exchange: the connection it opened, the request it sent and the response headers that came back.
Reference
Curl Flags Example
Curl has well over two hundred options.
How to Use Curl
Curl is a command-line program that makes network requests and prints what comes back.
Curl for Windows Example
Windows has shipped a real curl since 2018.
Wget vs Curl
Both fetch things from URLs and both are probably on your machine.
Curl Commands
The commands people reach for most, in one place and ready to copy.
Install Curl
Curl ships with macOS and with Windows 10 and 11, and it is one package away on every Linux distribution.
Converting curl
Convert Curl to Python Requests
A curl command and a call to the requests library describe the same HTTP request in different vocabularies.
Convert Curl to JavaScript Fetch
fetch() takes a URL and an options object that lines up closely with curl's flags.
Convert Curl to PHP
PHP's cURL extension is a wrapper around the same library the command-line tool uses, so every flag has a matching option.
Convert Curl to a Raw HTTP Request
Every curl command turns into a few lines of text sent over a socket.
Reading a curl command
Everything after the word curl is either a flag or the URL, in any order. Flags come in a short
form with one dash (-H) and a long form with two (--header); they are the same
option. Some take a value, which follows the flag. A trailing backslash continues the command on the next
line, purely for readability.
Three habits prevent most problems. Quote the URL and every header, because shells give meaning to
&, ?, $ and spaces. Add -i when a result surprises you,
since curl hides the status code by default. And when two requests that should be identical behave
differently, compare them with -v rather than by reading the commands.
How to use curl walks through this from the beginning, and the
flags reference lists the options worth knowing.
Official curl documentation
- curl project site — Downloads, release notes and the official documentation.
- curl man page — The complete reference for every command-line option.
- curl tutorial — The project's own introduction to using the tool.
- Everything curl — The free book by curl's maintainers, covering the tool end to end.
These links leave api-tester.com, which is independent of the projects they point to.
Curl examples FAQ
What is a curl command?
A line you run in a terminal that tells the curl program to make a network request. It consists of the word curl, optional flags that shape the request, and a URL.
What are the most useful curl commands?
A plain GET (curl URL), a GET showing headers (curl -i URL), a JSON POST (curl -H "Content-Type: application/json" -d '{...}' URL), an authenticated request (curl -H "Authorization: Bearer TOKEN" URL) and a download (curl -LO URL).
Why do API docs use curl for examples?
Because curl is installed almost everywhere, works the same on every platform, and expresses a complete HTTP request in one copyable line that is easy to translate into any programming language.
Can I run these curl examples without installing anything?
Curl is included with macOS, most Linux distributions and Windows 10 and 11. Examples marked with a Run button can also be sent from the browser through the API Tester on this site.