How to send binary data with cURL

Reliable transmission of binary data such as images, archives, and firmware prevents corruption during uploads and API calls. When raw bytes reach servers unchanged, deployments complete successfully and stored artifacts remain usable.

HTTP clients like curl send request bodies exactly as configured, so the chosen upload option directly affects how bytes are treated. Using --data-binary instructs curl to stream the file without URL encoding or newline conversion, while headers like Content-Type describe the payload format for the remote service.

Incorrect options or headers can silently damage binary formats or cause servers to reject uploads. Large payloads, authenticated endpoints, and constrained networks also introduce failure modes, so uploads benefit from checksum verification and careful selection of HTTP method and destination path.

1. Open a terminal in the environment that can reach the HTTP endpoint.
2. Change to the directory that contains the binary file.

   $ cd /work

   Using a working directory close to the payload avoids long /path/to/binaryfile references in later commands.

3. Send the binary file as the body of an HTTP POST request using --data-binary.

   $ curl --silent --data-binary "@./firmware.bin" "http://api.example.net/upload/binary"
   {
     "bytes": 524288
   }

   The @ prefix before /firmware.bin directs curl to read raw bytes from the file rather than treating the string as literal data.

4. Set an explicit Content-Type header that matches the file format when the server relies on MIME types.

   $ curl --silent --data-binary "@./firmware.bin" --header "Content-Type: application/octet-stream" "http://api.example.net/upload/binary"
   {
     "bytes": 524288
   }

   Common values include application/octet-stream for generic binaries and format-specific types such as image/png or application/zip.

5. Use the HTTP method required by the API when uploads must use verbs such as PUT.

   $ curl --silent --request PUT --data-binary "@./firmware.bin" "http://api.example.net/upload/binary"
   {
     "bytes": 524288
   }

   Many REST-style endpoints accept binary uploads on dedicated PUT URLs, while --data-binary ensures the payload itself remains unchanged.

6. Send binary data from standard input when another tool produces the bytes dynamically.

   $ cat firmware.bin | curl --silent --data-binary @- "http://api.example.net/upload/binary"
   {
     "bytes": 524288
   }

   The special path @- tells curl to read the request body from standard input rather than from a named file.

7. Avoid text-oriented upload options that can re-encode or rewrite the binary payload.

   Flags such as --data or --form may URL-encode characters or adjust newlines, which corrupts archives, executables, and firmware images.

8. Calculate a checksum of the original binary file to create a reference digest.

   $ sha256sum firmware.bin
   6ea6d1e4401f52de724fab224fc42e52722aa693b4cad9c1d06139ccfed7ca97  firmware.bin

9. Retrieve the stored copy from the server into a new local file for comparison.

   $ curl --silent "http://api.example.net/upload/binary" --output restored.bin

10. Recalculate the checksum of the restored file and verify it matches the original digest.

    $ sha256sum restored.bin
    6ea6d1e4401f52de724fab224fc42e52722aa693b4cad9c1d06139ccfed7ca97  restored.bin

    Matching checksum values for the original and restored files confirm that the binary transfer completed without corruption.