How to make a POST request with curl

curl is a command-line utility for transferring data from or to a remote server using one of the supported protocols. It is installed by default on Windows, macOS, and most Linux distributions.

System administrators, developers, and other users use curl to test APIs , view response headers, and make HTTP requests.

This article explains how to use curl to make POST requests.

cURL Options #

The HTTP POST method is used to send data to the remote server.

The general form of the curl command for making a POST request is as follows:

curl -X POST [options] [URL]

The -X option specifies which HTTP request method will be used when communicating with the remote server. In most cases, you do not need to set the method because it is determined from the command line options.

Making a POST request #

A typical POST request is sent via an HTML form, and the data sent to the form is usually encoded in the application/x-www-form-urlencoded format type. The data keys and values are encoded in key-value pairs, separated by the & symbol and with = between the key and the value.

To send a POST request with curl, use the -d (--data) option to specify the data:

curl -d 'name=linuxize&email=linuxize@example.com' https://example.com/form/

In the example above, we’re sending data to the remote server consisting of two key-value pairs: “name=linuxize” and “email=linuxize@example.com ”.

You can also send the data using multiple -d options. For example, the command above can also be written like this:

curl -d 'name=linuxize' -d 'email=linuxize@example.com' https://example.com/form/

When sending data to curl using the -d option, you should always correctly URL-encode all non-alphanumeric characters in both keys and values. For instance, if you are sending data that contains a name with spaces (“John Doe”), the command will look like this:

curl -d 'name=John%20Doe'  https://example.com/form/

However, it is a little inconvenient to manually encode the data that is not already encoded. In this case, it is better to use the --data-urlencode option that tells curl to encode the provided data. The command above, when used with the --data-urlencode option, will look like this:

curl --data-urlencode 'name=John Doe'  https://example.com/form/

The data passed to the curl command is usually in the key=value format. When you use the --data-urlencode option, only the value part is encoded. curl expect the key to be already URL encoded.

If you are sending data that contains a vast number of key-value pairs, instead of typing the data on the command line you can store it in a file, and pass that file to curl:

curl -d @name_of_the_file https://example.com/form/

When data provided to the command starts with the @ symbol, curl considers the data to be a file on the local system and will read and use the data from that file.

Making a POST request using Multipart Form Data #

The content type multipart/form-data is used when the form data contains binary files or other large-size payload data.

To create a multipart POST request, invoke the curl command with one or more -F (--form) options, followed by the key=value pairs. When the -F option is used, curl sends the data using the multipart/form-data Content-Type.

The following example shows how to make a POST request to a form that has “name” and “image” fields:

curl -F 'name=linuxize' -F 'image@photo.jpg' https://example.com/form/

Uploading Files #

To POST a file with curl, add the @ symbol before the file location. The file can be an archive, image, document, etc.

curl -F 'image=@/home/user/Pictures/wallpaper.jpg' http://example.com/upload/

POST JSON data with cURL #

JSON is a text-based data format that is used for data transfers between web services and APIs.

You can send JSON data using POST with curl using the --json option.

Here is a basic example of sending a JSON object to a server:

curl --json '{"website": "linuxize.com"}' http://example.com/api/

curl sends the JSON data as it is, so make sure it is in valid JSON format.

Same as with regular POST requests, you can use multiple --json options in one command:

curl --json '{"name": "Jonn"}' --json '{"age": "36"}'  http://example.com/api/

The JSON data can also be read from a local file:

curl --json @json_data.txt  http://example.com/api/

If you are using curl in a script, you can pipe JSON data from another command to curl, as shown below:

echo '{"website": "linuxize.com"}' | curl --json @- http://example.com/api/

The @- part means to read the body from the standard input.

Conclusion #

We’ve shown you how to use curl to make POST requests. For more information about curl, visit the Curl Documentation page.

If you have any questions or feedback, feel free to leave a comment.