curl is a command line tool for transferring data using various network protocols. Available on all major operating systems, curl has become the standard tool for sending HTTP requests from the command line.
curl’s cross-platform utility supports protocols like HTTP, HTTPS, FTP, and IMAP, making it easy to send requests to APIs and scrape websites using curl. With its wide availability and support for multiple protocols, you’ll often find curl referenced in REST API documentation as a quick way to test API calls directly from the command line:
In this article, you’ll learn how to send POST requests using curl from the command line.
What Is a POST Request
A POST request is an HTTP method to send data to a server and is one of the most common HTTP methods.
When you send a POST request, the transmitted data is included in the request body. This lets you send data more discreetly than sending it in the URL (like you would with a GET request). You can also send significantly more data in a POST request, circumventing the URL length restrictions imposed by browsers for GET requests.
You’ll often find POST requests used to submit forms, upload files, or send JSON data to an API. Compared to GET, POST requests are typically not cached, and the data isn’t shown in your browser history since the request data is in the body of the request.
How to Send a POST Request with curl
Before you begin this tutorial, you need to install curl on your computer. Run the following command to check if curl is installed:
curl --version
If you get an error saying the command could not be found, you need to install the utility.
Install curl
Following are the instructions on how to install curl on all major operating systems:
Windows
On Windows, you can use WinGet, the default package manager in Windows 11, to install curl:
winget install curl.curl
Chocolatey is another package manager for Windows that lets you install curl using the following command:
choco install curl
Linux
curl is available in most Linux package managers. On Ubuntu/Debian, use the following command to install curl:
apt-get install curl
Red Hat Enterprise Linux (RHEL), CentOS, and Fedora let you install curl using the Yellowdog Updater Modified (YUM), like this:
yum install curl
If you’re running OpenSUSE, you can install curl using the following terminal command:
zypper install curl
Finally, Arch Linux lets you use pacman to install curl with this command:
pacman -Sy curl
macOS
Homebrew is the easiest way to install curl on macOS. Make sure you have Homebrew installed, and then run the following command:
brew install curl
Now that you’ve installed curl on your operating system, you’re ready to learn how to make POST requests.
Make a POST Request
curl lets you specify several options when sending POST requests. The following sections will show some common curl features you might come across when making POST requests using the utility.
Specify the POST Method
When making HTTP requests using curl, you need to specify the HTTP method you want to perform. HTTP methods include GET, POST, PUT, and DELETE. curl lets you specify the HTTP method you wish to use using the -X command line flag.
For example, to send a POST request to https://httpbin.org/anything, you can execute the following curl command in your terminal:
curl -X POST https://httpbin.org/anything
httpbin.org echoes the request body and headers in the response. Your response should look like this:
{
"args": {},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": null,
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
The -X POST flag is the equivalent of using the --request POST flag, so you could also execute the following command and get the same result:
curl --request POST https://httpbin.org/anything
The response looks the same as the previous one.
You can read more about the -X and --request flags in the official documentation.
Set the Content-Type
When sending a POST request, it’s important to specify the type of content you’re sending in the body of the request so that the server can interpret the request body correctly. You can use MIME types in the Content-Type header in an HTTP request to specify the request body format.
For example, if you’re sending JSON in the request body, you need to tell the web server to expect JSON content by setting the Content-Type header to application/json. If you were sending XML, your Content-Type header should be application/xml. For more information, check out the official documentation discussing Content-Type.
curl lets you specify headers for an HTTP request using the -H flag. As an example, if you’re sending JSON in a POST request, the following curl command shows how you can set the Content-Type header for the request:
curl -X POST -H 'Content-Type: application/json' -d '{}' https://httpbin.org/anything
In the response, you can see the Content-Type header set to application/json:
{
"args": {},
"data": "{}",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Content-Length": "2",
"Content-Type": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=-11111111-111111111111111111111111"
},
"json": {},
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
The -H flag can also be specified using the longer --header flag. In this case, your curl command would look like this:
curl -X POST --header 'Content-Type: application/json' -d '{}' https://httpbin.org/anything
Your response would look the same as the previous one.
Send Data
You might have noticed the earlier commands had a -d flag. This flag lets you specify the data to send in the request body. You can use the flag to pass any string of values surrounded by quotations, like this:
curl -X POST -H 'Content-Type: application/json' -d '{
"FirstName": "Joe",
"LastName": "Soap"
}' https://httpbin.org/anything
You’ll notice that httpbin.org shows the body data you sent in the data property of the response.
If you have a file with data that you want curl to send in the body, specify the file name prefixed with the @ character. The following command reads the contents of body.json and sends it through the request body:
curl -X POST -H 'Content-Type: application/json' -d @body.json https://httpbin.org/anything
In this case, the body.json file contains the following:
{
"FirstName": "Joe",
"LastName": "Soap"
}
When sending this, httpbin.org should return the following response:
{
"args": {},
"data": "{\t\"FirstName\": \"Joe\",\t\"LastName\": \"Soap\"}",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Content-Length": "41",
"Content-Type": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": {
"FirstName": "Joe",
"LastName": "Soap"
},
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
The --data flag behaves the same as -d, so you can use them interchangeably.
Send JSON Data
In the previous section, you saw how you could send JSON data by setting the Content-Type header to application/json and then passing in the JSON data using the -d flag. When sending a request, it’s also important to let the web server know what format of data you expect in response. You can use the Accept header with the value application/json to let the web server know you’d like to receive a JSON response.
The following command sends a JSON request to the server and lets the server know you’d like to receive JSON in response:
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"FirstName": "Joe",
"LastName": "Soap"
}' https://httpbin.org/anything
You’ll notice the data and json properties in the response body contain the JSON data you sent in the request:
{
"args": {},
"data": "{\n \"FirstName\": \"Joe\",\n \"LastName\": \"Soap\"\n}",
"files": {},
"form": {},
"headers": {
"Accept": "application/json",
"Content-Length": "50",
"Content-Type": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": {
"FirstName": "Joe",
"LastName": "Soap"
},
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
Sending and receiving JSON data is common when sending HTTP requests, so curl offers a --json flag that sets the Content-Type and Accept headers for you and sends the JSON data in the request body. Using this flag, you can shorten your command to send JSON in a POST request:
curl -X POST --json '{
"FirstName": "Joe",
"LastName": "Soap"
}' https://httpbin.org/anything
This yields the same response as before:
{
"args": {},
"data": "{\n \"FirstName\": \"Joe\",\n \"LastName\": \"Soap\"\n}",
"files": {},
"form": {},
"headers": {
"Accept": "application/json",
"Content-Length": "50",
"Content-Type": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": {
"FirstName": "Joe",
"LastName": "Soap"
},
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
The --json flag was released in version 7.82 of curl in March 2022, so make sure you have the latest version of curl installed before you use it.
Send XML Data
curl also lets you send data in other formats, such as XML. To send XML data, you need to set your Content-Type header to application/xml and pass the XML data in the request body using the -d flag. You can also tell the web server you expect the response to be XML by setting the Accept header to application/xml.
The following command shows how you can send an XML object in a POST request using curl:
curl -X POST -H 'Content-Type: application/xml' -H 'Accept: application/xml' -d '<Person>
<FirstName>Joe</FirstName>
<LastName>Soap</LastName>
</Person>' https://httpbin.org/anything
You’ll find the XML request data in the data property returned by httpbin.org:
{
"args": {},
"data": "<Person>\n <FirstName>Joe</FirstName>\n <LastName>Soap</LastName>\n</Person>",
"files": {},
"form": {},
"headers": {
"Accept": "application/xml",
"Content-Length": "79",
"Content-Type": "application/xml",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": null,
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
Send FormData
You can use FormData to send key-value pairs of data to a web server. As the name implies, you use this data format when submitting a form on a web page. The key-value pairs have a field name and value.
curl lets you specify FormData using the -F or --form flag. When using the flag, specify the field name and value in the following format: -F <name=content> or --form <name=content>.
The next snippet shows a curl command that sends a POST request using FormData with FirstName and LastName fields:
curl -X POST -F FirstName=Joe -F LastName=Soap https://httpbin.org/anything
You’ll find the form field names and values in the form property of the httpbin.org response object:
{
"args": {},
"data": "",
"files": {},
"form": {
"FirstName": "Joe",
"LastName": "Soap"
},
"headers": {
"Accept": "*/*",
"Content-Length": "248",
"Content-Type": "multipart/form-data; boundary=------------------------e2bb56049a60b8b8",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": null,
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
You use the -F flag for every field you want to send to the server.
Upload Files
You can use FormData to upload files in a POST request by attaching the file to a field. To let curl know a FormData field holds a file, enter the path to the file in the field value prefixed with the @ character.
The following curl command uploads a file called Contract.pdf in your working directory. The command uses a field called File to upload the file:
curl -X POST -F [email protected] https://httpbin.org/anything
The response contains the whole file, so it’s long, but it should look like this:
{
"args": {},
"data": "",
"files": {
"File": "..."
},
"form": {},
"headers": {
"Accept": "*/*",
"Content-Length": "246",
"Content-Type": "multipart/form-data; boundary=------------------------19ed1fc3be4d30c7",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": null,
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
Send Credentials
Many HTTP endpoints require authentication to send requests. The web server decides what authentication method you should use. One such authentication method is the basic authentication scheme, which lets you send credentials consisting of a username and password in your request. The server then verifies the credentials and, if correct, processes the request.
curl simplifies sending basic authentication credentials using the -u or --user flag. You then specify the username and password and separate them with a : (colon), like this: -u <username:password>.
The following snippet uses curl to send a POST request with user credentials and a JSON body:
curl -X POST -u 'admin:password123' --json '{
"FirstName": "Joe",
"LastName": "Soap"
}' https://httpbin.org/anything
Notice how curl encodes the username and password and sends it in the Authorization header:
{
"args": {},
"data": "{\n \"FirstName\": \"Joe\",\n \"LastName\": \"Soap\"\n}",
"files": {},
"form": {},
"headers": {
"Accept": "application/json",
"Authorization": "Basic YWRtaW46cGFzc3dvcmQxMjM=",
"Content-Length": "50",
"Content-Type": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2",
"X-Amzn-Trace-Id": "Root=1-11111111-111111111111111111111111"
},
"json": {
"FirstName": "Joe",
"LastName": "Soap"
},
"method": "POST",
"origin": "0.0.0.0",
"url": "https://httpbin.org/anything"
}
Conclusion
This article showed you how to send POST requests using the curl command line utility. You learned how to use the -X flag to specify that you want to send a POST request. You also set the Content-Type and Accept headers using the -H and --header flags so that the web server knows what format the data is in. To send data in the request body, you used the -d flag along with the data you wanted to send.
You also saw a few examples of how to send several types of data, including JSON, XML, and FormData, and learned how to send basic authentication credentials in your request using the -u and --user flags.
While this article demonstrated the basic flags included in curl and how to use them, curl offers more features that you might want to explore, including using variables, sending cookies with requests, and sending requests using a proxy. Many programming languages also provide libraries that let you work with curl from that programming language, including Python, Node.js, and Rust.
Looking for a scraping solution? Register now and talk to one of our data experts and see which one of our products best suits your needs.
