cURL: POST request examples

cURL HTTP POST request examples with my most frequently used command-line options.

You can also check my other cURL guides for GET requests, PUT requests, and DELETE requests.

HTTP POST request

The most basic command you can execute with cURL is an HTTP POST request without a body.

To tell cURL to use a POST request method we can use the -X, --request command-line option, the following command will perform the request and output the response body:

curl -X POST https://blog.marcnuri.com

HTTP POST request with data

Whenever you perform a POST request, it's very likely that you need to send some type of data along with it.

To send some data with the POST request we can use the -d, --data command-line option. This will cause curl to send data the same way it does when you fill a browser HTML form and press the submit button. It will also cause cURL to add the Content-Type header with an application/x-www-form-urlencoded value.

curl -X POST -d "field=value&tool=curl" https://postman-echo.com/post

HTTP POST request to upload a file

To upload a file using cURL you can use the -F, --form command-line option. Similar to the --data option, this lets cURL simulate a user sending a filled in HTTP form by pressing the submit button.

In this case, cURL adds the Content-Type header, but with a multipart/form-data value instead.

curl -X POST -F "field=@/path/to/file.txt" https://postman-echo.com/post

Notice the @ symbol before the path to the file. This forces cURL to attach the file as a file upload.

You can use this method to send data for as many fields as you want:

curl -X POST -F "field=@/path/to/file.txt" -F "tool=curl" -F "other-file=@/path/to/other" https://postman-echo.com/post

Upload a file with a custom filename

If you want to change the name of the file you're uploading you can achieve this by tweaking a little the value of the field you provide for the cURL command. You need to add ;filename= followed by the name of the file you want to use instead just after the path to the file you are attaching.

curl -X POST -F 'field=@"/path/to/file.txt";filename="other-name.txt' https://postman-echo.com/post

HTTP POST request with JSON data

To perform an HTTP POST request with JSON content in the request body you can use the -d, --data options in combination with a custom Content-Type header (-H, --header).

curl -X POST -d '{"field":"value"}' -H "Content-Type: application/json" https://postman-echo.com/post

JSON from file

In case you want to load the JSON content from a file instead of providing it via command-line, you can load it using the @ symbol followed by the path to the file that contains the JSON data:

curl -X POST -d "@file-with-json.json" -H "Content-Type: application/json" https://postman-echo.com/post

HTTP POST request with authentication

When posting data to protected endpoints, you'll need to provide authentication credentials along with your request.

Basic authentication

For HTTP Basic authentication, use the -u, --user command-line option:

curl -X POST -u username:password -d '{"field":"value"}' -H "Content-Type: application/json" https://api.marcnuri.com/data

Bearer token authentication

For APIs that use Bearer tokens (OAuth 2.0, JWT, etc.), add an Authorization header:

curl -X POST -H "Authorization: Bearer your-token-here" -d '{"field":"value"}' -H "Content-Type: application/json" https://api.marcnuri.com/data

Summary

These are some of the common cURL POST HTTP request examples I use on a daily basis. I hope they may come in useful for you too.

References

• The book: Everything curl
• cURL Man Page