How to Make POST Requests using cURL

How can we perform POST requests using cURL?

cURL is a command-line utility that allows us to perform network requests.

We can easily utilize this tool to make POST requests in the command line.

cURL configuration options

Setting request type

If we run curl followed by some target URL, a GET request will be made by default.

curl https://example.com

We can specify the request method to use using the -X flag.

-X POST
-X PUT

Setting Content-Type headers

Two common formats for POST requests are application/json and application/x-www-form-urlencoded.

We can set this Content-Type header using the -H flag.

-H "Content-Type: application/x-www-form-urlencoded"
-H "Content-Type: application/json"

By default, cURL will send data with the application/x-www-form-urlencoded format, so it is unnecessary to specify that content type.

Sending data

Generally, we’ll want to send some data with our POST requests.

To do this, we can use the -d flag.

-d "key=val1&key2=val2" # application/x-www-form-urlencoded
-d '{"key1":"val1", "key2":"val2"}' # application/json

We can also reference files for these key-value pairs.

For instance, a data.txt file for application/x-www-form-urlencoded.

key=val1&key2=val2

Or data.json for application/json.

{ "key1":"val1", "key2":"val2" }

We can then use the @ symbol to reference these files.

-d @data.txt # application/x-www-form-urlencoded
-d @data.json # application/json

If we use the -d flag with a POST request (rather than a PUT), we can actually omit -X POST from our cURL command. Sending data with -d defaults to a POST request.

cURL examples

Putting it all together, this is what POST requests would look like with cURL.

POST application/x-www-form-urlencoded

curl -d "key1=val1&key2=val2" -X POST https://example.com
curl -d "key1=val1&key2=val2" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://example.com
curl -d "@data.txt" -X POST https://example.com

POST application/json

curl -d '{"key1":"val1", "key2":"val2"}' -H "Content-Type: application/json" -X POST https://example.com
curl -d "@data.json" -H "Content-Type: application/json" -X POST https://example.com

cURL command line options

From man curl, here are a list of available flags to use with curl.

• -#, --progress-bar: Make curl display a simple progress bar instead of the standard, more informational, meter.
• -b, --cookie <name=data>: Supply cookie with request. If no =, then specifies the cookie file to use (see -c).
• -c, --cookie-jar <file name>: File to save response cookies to.
• -d, --data <data>: Send specified data in POST request. Details provided below.
• -f, --fail: Fail silently (don’t output HTML error form if returned).
• -F, --form <name=content>: Submit form data.
• -H, --header <header>: Headers to supply with request.
• -i, --include: Include HTTP headers in the output.
• -I, --head: Fetch headers only.
• -k, --insecure: Allow insecure connections to succeed.
• -L, --location: Follow redirects.
• -o, --output <file>: Write output to . Can use --create-dirs in conjunction with this to create any directories specified in the -o path.
• -O, --remote-name: Write output to file named like the remote file (only writes to current directory).
• -s, --silent: Silent (quiet) mode. Use with -S to force it to show errors.
• -v, --verbose: Provide more information (useful for debugging).
• -w, --write-out <format>: Make curl display information on stdout after a completed transfer. See man page for more details on available variables. Convenient way to force curl to append a newline to output: -w "\n" (can add to ~/.curlrc).
• -X, --request: The request method to use.