cURL POST Request Guide

{ "@context": "https://schema.org", "@type": "HowTo", "name": "Sending POST Requests Using curl from the Command Line", "description": "A comprehensive guide on how to use curl to send POST requests from the command line, covering everything from what a POST request is to various curl commands for sending data, JSON, XML, FormData, files, credentials, and handling authentication.", "step": [ { "@type": "HowToStep", "name": "Verify curl Installation", "text": "Check if curl is installed on your computer by running 'curl --version' in the command line. If not installed, proceed to install curl according to your operating system's instructions." }, { "@type": "HowToStep", "name": "Understand What a POST Request Is", "text": "Learn about POST requests, an HTTP method used to send data to a server. Unlike GET requests, POST requests include data in the request body, allowing for more discreet and voluminous data transmission." }, { "@type": "HowToStep", "name": "Install curl on Your Operating System", "text": "Install curl on Windows, Linux, or macOS. Use the appropriate package manager or download from the official site, following specific installation instructions for your operating system." }, { "@type": "HowToStep", "name": "Make a POST Request with curl", "text": "Use curl to send a POST request by specifying the HTTP method with the -X command line flag, and optionally set the Content-Type header and data to be sent in the request body using -H and -d flags respectively." }, { "@type": "HowToStep", "name": "Set the Content-Type Header", "text": "When sending data in a POST request, use the -H flag to specify the Content-Type header according to the type of data being sent (e.g., application/json for JSON data)." }, { "@type": "HowToStep", "name": "Send Data in the Body of the Request", "text": "Use the -d flag to include data in the body of your POST request. You can pass a string directly or use '@' to specify a file containing the data to be sent." }, { "@type": "HowToStep", "name": "Send JSON Data", "text": "To send JSON data, set the Content-Type to application/json and use the -d flag with a JSON-formatted string, or use the --json flag for convenience." }, { "@type": "HowToStep", "name": "Send XML Data", "text": "To send XML data, specify the Content-Type as application/xml and pass the XML content using the -d flag." }, { "@type": "HowToStep", "name": "Send FormData", "text": "For submitting form-like data, use the -F flag to include key-value pairs representing form fields and values." }, { "@type": "HowToStep", "name": "Upload Files", "text": "Use the -F flag with a field name and file path prefixed with '@' to upload files in a POST request." }, { "@type": "HowToStep", "name": "Send Credentials for Authentication", "text": "For endpoints requiring authentication, use the -u flag to include username and password credentials in the request." } ], "estimatedCost": { "@type": "MonetaryAmount", "currency": "USD", "value": "0" }, "supply": [ { "@type": "HowToSupply", "name": "A computer with Internet access" }, { "@type": "HowToSupply", "name": "curl installed on the operating system" } ], "tool": [ { "@type": "HowToTool", "name": "curl command line utility" } ], "totalTime": "PT10M" }

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:

learn how to send POST requests using curl 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"
}

All The Important cURL Arguments

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.