curl Multipart Form Data

Multipart Form Data with curl

Multipart form data (multipart/form-data) is the standard encoding for HTML forms that include file uploads. curl's -F flag makes it easy to construct these requests.

Basic Form Submission

curl -X POST https://example.com/form \
  -F "name=Alice" \
  -F "email=alice@example.com"

Each -F flag creates a form field. curl automatically sets the Content-Type to multipart/form-data with a randomly generated boundary.

File with Form Fields

curl -X POST https://example.com/upload \
  -F "avatar=@photo.jpg" \
  -F "username=alice" \
  -F "bio=Hello world"

The @ prefix on the value tells curl to read file contents. Without @, the value is sent as a plain text field.

Custom Content Type for File

Override the auto-detected MIME type:

curl -X POST https://example.com/upload \
  -F "document=@report.pdf;type=application/pdf"

Custom Filename

Send a file with a different name:

curl -X POST https://example.com/upload \
  -F "file=@/tmp/temp123.csv;filename=report.csv"

Multiple Files in One Field

curl -X POST https://example.com/upload \
  -F "attachments=@file1.pdf" \
  -F "attachments=@file2.pdf" \
  -F "attachments=@file3.pdf"

File Content from stdin

echo "Hello World" | curl -X POST https://example.com/upload \
  -F "file=@-;filename=greeting.txt"

Difference Between -F and -d

Flag	Content-Type	Use Case
-F	multipart/form-data	File uploads, mixed data
-d	application/x-www-form-urlencoded	Simple key-value forms

Complex Multipart Example

curl -X POST https://api.example.com/documents \
  -F "file=@contract.pdf;type=application/pdf;filename=contract-2026.pdf" \
  -F "metadata={"category":"legal","priority":"high"};type=application/json" \
  -H "Authorization: Bearer token123"

This sends a PDF file alongside JSON metadata in a single multipart request, which is a common pattern for document management APIs.