How to Send cURL POST Requests: Step-by-Step Guide

What is a POST Request?

A POST request is how you send data to a server in order for it to create or update something on its end. The payload is in the request body instead of being in the URL, which creates a cleaner URL and allows you to send large or structured data like JSON, XML, form fields, and files. POST is the preferred method for actions like user sign up, submitting checkout details, uploading images, and running background tasks. Since a POST performs an action, if you submit the same request twice, the same action will happen twice, so be careful if you retry.

How to Send a POST Request with cURL: Step-by-Step

Install cURL on Your OS

First, you'll need to install cURL if you don’t have it yet. Most Linux distros already include it; otherwise use your package manager.

Debian or Ubuntu: sudo apt install curl
Fedora: sudo dnf install curl
macOS: ships with cURL, or install the latest via Homebrew: brew install curl
Windows 10 and later: winget install curl or install Git for Windows which includes cURL

Confirm your version with:

curl --version

Make Your First POST Request

The quickest form encoded POST looks like this:

curl -d "name=Alice&age=30" https://api.example.com/users

Using -d automatically selects the POST method and sets the body as application/x-www-form-urlencoded. If you prefer to be explicit, you can add -X POST and a header:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Alice&age=30" https://api.example.com/users

You can repeat -d to add more fields. cURL will join them with &.

A Quick Overview of POST Request Arguments You Will Actually Use

The table below will assist you in making the appropriate cURL choices for daily use in posting requests quickly. Simply scan the left column to find the appropriate flag, read the brief description, grab the example, and paste it into your terminal.

Table which include cURL POST request arguments.

Send JSON Payloads

Now that you have the quick overview, here is how to post JSON in practice.

Inline JSON:

curl -X POST https://api.example.com/items \
  -H "Content-Type: application/json" \
  -d '{"name":"Book","price":9.99}'

From a file for cleaner workflows:

curl -X POST https://api.example.com/items \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

Tip: prefer --data-binary when posting a file so cURL does not alter newlines or bytes.

Send XML Payloads

If your service uses XML, the flow is the same. Point cURL at the endpoint, set the header, and send the body.

curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/xml" \
  --data-binary @order.xml

Small XML can be sent inline, but putting it in a file keeps complex payloads readable and easy to version.

Send Form Data

There are two common web form formats, and cURL handles both.

URL encoded forms

curl https://api.example.com/signup \
  --data-urlencode "email=user@example.com" \
  --data-urlencode "name=Jane Doe"

--data-urlencode makes sure spaces and special characters are encoded correctly.

Multipart forms

curl -X POST https://api.example.com/upload \
  -F "title=Summer Trip" \
  -F "photo=@beach.jpg"

cURL will build a browser style multipart/form-data request. You can also hint the media type:

curl -X POST https://api.example.com/upload \
  -F "photo=@beach.jpg;type=image/jpeg"

Use multipart when you need to mix text fields and files in one request.

Upload a File or Multiple Files via POST

To send more than one file, repeat -F:

curl -X POST https://api.example.com/gallery \
  -F "photos[]=@1.jpg" \
  -F "photos[]=@2.jpg" \
  -F "photos[]=@3.jpg"

If your endpoint expects raw bytes rather than multipart, post the file as the entire body:

curl -X POST https://api.example.com/raw \
  -H "Content-Type: application/octet-stream" \
  --data-binary @archive.tar

Rule of thumb: use multipart for form style uploads, and use --data-binary @file for endpoints that accept a single raw payload.

Send Authentication Credentials

Basic auth

curl -u "username:password" -X POST https://api.example.com/login

If you omit the password, cURL will prompt you:

curl -u "username" -X POST https://api.example.com/login

Bearer tokens

curl -X POST https://api.example.com/secure \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"ping"}'

Cookie based sessions

# Log in and save cookies
curl -c cookies.txt -d "user=a&pass=b" https://api.example.com/login

# Reuse cookies for an authenticated POST
curl -b cookies.txt -d "something=1" https://api.example.com/endpoint

Important note

Don't forget to replace username and password with your real credentials, and swap every example URL with your own endpoint before running the commands. If you are using a token, substitute $API_TOKEN with your actual value.

Conclusion

You now have everything you need to send solid POST requests with cURL from the terminal. Start simple with -d for classic form fields, reach for --data-urlencode when special characters show up, use --data-binary when you are posting files or need exact bytes, and switch to -F for multipart uploads with text plus files. Add headers with -H, include credentials with -u or a bearer token, and lean on cookies with -c and -b when a session is involved. While you are testing, -i, -v, and -L make troubleshooting much easier, and -o saves responses cleanly.

Now if you want more guides related to cURL and you are a beginner, you can check our quick guide on using cURL to send GET requests and when you learned more about cURL and want to take it to the next level, check using cURL with a proxy. Also, if you have any questions, you can contact our support team and they will help you resolve any problem you've got.