Curl Post Request

cURL (curl) is an open source command-line tool used for transferring data over a network. POST is an HTTP request method which is used to send data to the server. (Read more on POST requests here.)

The format of a POST request with curl is: curl -X POST [options] [URL].

An example POST request to submit a todo list task to a REST API might look like:

 curl -H 'Content-Type: application/json' \
      -d '{ "title":"foo","body":"bar", "id": 1}' \
      -X POST \
      https://example.com/posts

Three options provided here are:

• -X was used to provide the HTTP method we use to send the request. In this case, the method is POST
• -d was used to provide the associated data in the body of the HTTP request
• -H was used to specify headers for the request

Each of these options also have associated aliases. For example, for -X you can instead provide --request, and for -H you can provide --headers.

These are just some of the possible options, but there are many others, enumerated below.

Common POST Request Operations

Sending Form Data

There are two common ways to send form data with POST requests, each with different content-types, demonstrated below:

# multipart/form-data
## Text Field
curl -H "Content-type: multipart/form-data" \
     -F title=foo \
     -F body=bar \
     -F id="1" \
     -X POST \
     https://example.com/posts

## Image Upload
curl -H "Content-type: multipart/form-data" \
     -F [email protected] \
     https://example.com/avatar.cgi

# application/x-www-form-urlencoded
curl -H "Content-type: application/x-www-form-urlencoded" \
     -d "title=foo" \
     -d "body=bar" \
     -d "id=1" \
     -X POST \
     https://example.com/posts

As we can see from the image, to use multipart/form-data content-type, we send data with the -F (or --form option). To use application/x-www-form-urlencoded content-type, we use the -d (or --data) option.

Generally speaking, multipart/form-data is more often used to send binary data like images, while application/x-www-form-urlencoded is used to send text data.

By default, HTML forms will send data using the content-type of application/x-www-form-urlencoded when submitted.

Sending Image Data

To send image data in a POST request, include the image in the form data by prefixing the filename with an @ symbol as follows:

 curl -F [email protected] \
     https://example.com/avatar.cgi

The @ symbol forces the content part of the form to be a file, which is then uploaded to the server.

Alternatively, we could base64 encode the image and send it as a field in a form field or JSON body field of your request, but this is far less ergonomic:

 curl -H 'Content-Type: application/json' \
     -d  '{"image" : "'"$(base64 ~/avatar.jpg)"'"}' \
     -X POST \
     https://example.com/avatar.cgi

Common Gotchas

• Argument names are case sensitive. For example, -F corresponds to the argument for form data, while -f is a flag indicating whether we want to fail fast with no output
• When passing content of type application/json, be sure to wrap the JSON body in single quotes - e.g. -d "{ "title":"foo" }" would be invalid
• You can only use breaklines if you include \ a backslash character. There can be no trailing spaces after the backslash

cURL POST Request Arguments

Arguments available for the options field of the curl POST format (curl -X POST [options] [URL]) are enumerated below:

‍

Read more on the official curl docs.