Guide to Sending Post Request via cURL With Data From a File

1. Overview

cURL is a command-line tool in Linux for sending and receiving files over multiple supported protocols such as HTTP, HTTPS, and FTP.

In this tutorial, we’ll learn how to send a POST request via cURL with data from a file.

2. Basics

cURL supports multiple ways to send data from a file with a POST request. In this section, let’s develop a basic understanding of working with file data using the curl command.

First, we need an endpoint that accepts the requests from clients. So, let’s visit the webhook.site and initialize the server_endpoint variable with the address:

server_endpoint="https://webhook.site/5610141b-bd31-4940-9a83-1db44ff2283e"

Next, let’s get a sample JSON file and make a curl request to send its data using the –data option:

$ curl --header "Content-Type: application/json" \
> --data "$(cat ~/Downloads/sample1.json)" \
> --trace-ascii trace-json-data-request.log \
> $server_endpoint

We must note that we’re using the –trace-ascii option for tracing the curl request so that we can use it for verifying the requests.

Alternatively, we could also use the @file notation to let curl read the data from the file internally:

$ curl --header "Content-Type: application/json" \
> --data "@~/Downloads/sample1.json" \
> --trace-ascii trace-json-data-request.log \
> $server_endpoint

Finally, let’s inspect the trace-json-data-request.log file to verify that we’ve sent the data successfully:

$ grep --max-count=1 --after-context=2 "Send data"  trace-json-data-request.log
=> Send data, 65 bytes (0x41)
0000: {.    "fruit": "Apple",.    "size": "Large",.    "color": "Red".
0040: }

It looks like we’ve got this right.

3. Sending File Data With Metadata

The typical use case for sending file data over a POST request is when an end-user fills out a form and submits it to the server. So, the request must support sending other metadata along with the file data. To solve such a use case, curl supports the –form option to post the data with the multipart/form-data Content-Type header according to RFC-2388.

Let’s go ahead, download a sample gif file, and send the file data along with a few user details:

$ curl --form '[email protected];type=image/gif' \
--form 'username=baeldung' \
--form 'user_id=123' \
--trace-ascii trace-form-request.log
$server_endpoint

Next, let’s inspect the trace-form-request.log file and verify that the request was dispatched correctly:

$ grep --max-count=3 \
--after-context=2 \
--before-context=1 \
-e 'username' -e 'user_id' -e 'gif' \
trace-form-request.log
006c: f"
0070: Content-Type: image/gif
0089:
008b: GIF89a.......................................................#..
--
6bb5: --------------------------b17d10ecc2112c14
6be1: Content-Disposition: form-data; name="username"
6c12:
6c14: baeldung
6c1e: --------------------------b17d10ecc2112c14
6c4a: Content-Disposition: form-data; name="user_id"
6c7a:
6c7c: 123

We notice that curl understands the image/gif Content-Type and conveniently sends the file data to the server. Furthermore, using –before-context and –after-context options with the grep command allows us to see the content from the trace-form-request.log file before and after the matching lines.

Finally, let’s verify the file received on the server side by downloading it from the webhook.site page:

We can see that the Form values section contains the username and user_id keys along with their values, while the Files section contains the sample.gif file.

However, we must note that using this approach won’t work for non-textual files such as mp3, jpeg, etc.

4. Sending Multiple Files

In this section, we’ll extend the approach of sending a single file using curl with the –form option to multiple files.

Let’s download two sample mp3 files and POST them using curl with the –form option:

$ curl --form '[email protected];type=audio/mp3' \
--form '[email protected];type=audio/mp3' \
--trace-ascii trace-form-request-multi-files.log \
$server_endpoint

Next, let’s inspect the trace-form-request-multi-files.log file and verify that the request was dispatched as expected:

$ grep --max-count=6 --after-context=2 --before-context=1 -e 'mp3' trace-form-request-multi-files.log
002c: Content-Disposition: form-data; name="file1"; filename="sample1.
006c: mp3"
0072: Content-Type: audio/mp3
008b:
008d: ID3......#TSSE.......Lavf57.83.100.............P................
--
d25f: Content-Disposition: form-data; name="file2"; filename="sample2.
d29f: mp3"
d2a5: Content-Type: audio/mp3
d2be:
=> Send data, 65536 bytes (0x10000)

It looks correct.

Finally, let’s visit the webhook.site page to confirm that the server received the files successfully:

We can notice that the Files section contains the sample1.mp3 and sample2.mp3 files.

5. Conclusion

In this article, we explored the technique of sending data from files using cURL. Furthermore, we learned about the –data and –form options to solve the use cases.