Documentation Python quickstart Blog Free tools Enterprise solutions hello@quanticdata.ioLog in

curl POST request: JSON body, form data, files and Windows quoting

Three ways to send a curl POST request and the Content-Type each one sends: -d with name=Ada sends application/x-www-form-urlencoded, --json sends application/json with Accept application/json, -F with file=@rows.csv sends multipart/form-data; the card notes that in Windows PowerShell 5.1 a JSON body needs escaped quotes or @file.
Three ways to send a curl POST request and the Content-Type each one sends: -d with name=Ada sends application/x-www-form-urlencoded, --json sends application/json with Accept application/json, -F with file=@rows.csv sends multipart/form-data; the card notes that in Windows PowerShell 5.1 a JSON body needs escaped quotes or @file.

To send a POST request with curl, add a body: curl -d "name=Ada" URL posts form data, curl --json '{"name":"Ada"}' URL posts JSON with the right headers, and curl -F "file=@rows.csv" URL uploads a file. Each one switches curl to POST, so -X POST is not needed.

We sent every request below to httpbin.org/post, which echoes back what it received, on 20 November 2026 with curl 8.22.0 on Windows 11, directly and through QuanticData proxies. The output is real; exit IPs are masked and the trace header httpbin adds is left out.

The three kinds of POST body

OptionBody sentContent-Type curl setsUse it for
-d "name=Ada&lang=en"name=Ada&lang=en (16 bytes)application/x-www-form-urlencodedHTML forms, simple APIs
--json '{"name":"Ada"}'the JSON text (14 bytes)application/json, plus Accept: application/jsonJSON APIs
-F "file=@rows.csv" -F "note=test"multipart partsmultipart/form-data; boundary=...File uploads
--data-urlencode "q=a&b c"q=a%26b%20c, decoded by the server as a&b capplication/x-www-form-urlencodedValues with &, spaces or =

POST form data with -d

$ curl -sS -d "name=Ada&lang=en" https://httpbin.org/post
{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "16",
    "Content-Type": "application/x-www-form-urlencoded",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.22.0"
  },
  "method": "POST",
  "origin": "x.x.x.x",
  "url": "https://httpbin.org/post",
  "data": "",
  "files": {},
  "form": {
    "lang": "en",
    "name": "Ada"
  },
  "json": null
}

Several -d options are joined with &. -d sends the text as you typed it, so a value with & or a space breaks the form; --data-urlencode encodes it for you. With -v you can see the request line curl built: > POST /post HTTP/1.1, then Content-Length: 3 and the form Content-Type for -d "a=1".

POST JSON: --json, or -H plus -d

On curl versions that have it (ours, 8.22.0, does), --json does three things at once: it sends the body, sets Content-Type: application/json and sets Accept: application/json. On an older curl, set the header yourself:

curl --json '{"name":"Ada"}' https://httpbin.org/post
curl -H "Content-Type: application/json" -d '{"name":"Ada","tags":["a","b"]}' https://httpbin.org/post

Both arrived as JSON: httpbin put the parsed object under "json". The difference is the Accept header: */* with -H and -d, application/json with --json. Without the Content-Type header, a body sent with plain -d is labelled as form data, and many JSON APIs reject it.

The JSON body from a file

Put @ before a file name to send the file's content. It is the cleanest way to send long JSON, and it worked unchanged in bash and in PowerShell:

$ cat body.json
{"query":"residential proxies","limit":5}
$ curl -sS --json @body.json https://httpbin.org/post
...
  "data": "{\"query\":\"residential proxies\",\"limit\":5}",
  "json": {
    "limit": 5,
    "query": "residential proxies"
  }

POST JSON from Windows PowerShell and cmd

This is where most Windows users lose time. In Windows PowerShell 5.1, the command that works in bash sends broken JSON to curl.exe, because the inner double quotes are dropped on the way to the program:

Shell and commandBody the server received
PowerShell 5.1: curl.exe --json '{"name":"Ada"}' URL{name:Ada} (not valid JSON)
PowerShell 5.1: curl.exe --json '{\"name\":\"Ada\"}' URL{"name":"Ada"}
PowerShell 5.1: curl.exe --json '@body.json' URLthe file, intact
cmd: curl --json "{\"name\":\"Ada\"}" URL{"name":"Ada"}

Two more Windows details: in PowerShell type curl.exe, because curl alone is an alias of Invoke-WebRequest; and quote '@body.json', because @ means something to PowerShell. The guide to proxies in PowerShell covers the alias.

Upload a file with -F

$ printf 'id,name\n1,Ada\n' > rows.csv
$ curl -sS -F "file=@rows.csv" -F "note=test" https://httpbin.org/post
...
    "Content-Type": "multipart/form-data; boundary=------------------------6EbHxT81aN8yBlUZv89mhw",
...
  "files": {
    "file": "id,name\n1,Ada\n"
  },
  "form": {
    "note": "test"
  }

-F "file=@rows.csv" attaches the file as a part named file; -F "note=test" adds a plain field next to it. Use -F when a web form has a file input, and -d or --json for everything else.

Status code, errors and redirects

  • Only the status: curl -sS -o /dev/null -w "%{http_code}\n" --json '{"a":1}' URL printed 200.
  • Fail on HTTP errors: curl exits 0 on a 404 or 500 unless you add -f. With -f a POST to a 404 printed "curl: (22) The requested URL returned error: 404" and exited 22.
  • Redirects change the method. With -L, a POST answered with 302 was followed as a GET and the form was lost; after a 307 curl kept the POST and the body. With --post302 added, curl kept the POST after the 302 as well.
  • -G turns -d into a query string: curl -G -d "q=proxy" -d "page=2" URL sent a GET to /get?q=proxy&page=2.
  • -X POST alone sends a POST with no body; only use it when an API wants an empty POST.

POST through a proxy

Add -x for the proxy and -U for its username and password; the POST options stay the same. httpbin's origin field shows the address the site saw:

curl -x http://residentialboson.quanticdata.io:10000 -U "USER-type-residential-country-us-session-ca01-lifetime-30:PASS" --json '{"via":"residential-basic"}' https://httpbin.org/post
curl -x http://mobile.quanticdata.io:8080 -U "USER-country-us-type-mobile-sid-ca03-ttl-30m:PASS" --json '{"via":"mobile"}' https://httpbin.org/post
curl -x http://residentialpremium.quanticdata.io:8080 -U "USER-country-de-sid-ca02-ttl-30m:PASS" -d "via=residential-premium" https://httpbin.org/post
NetworkBodyorigin seen by the siteEchoed back
Residential Basic, USJSON, 27 bytesx.x.x.x (a US address)"json": {"via": "residential-basic"}
Mobile, USJSON, 16 bytesx.x.x.x (a US address)"json": {"via": "mobile"}
Residential Premium, Germanyform, 23 bytesx.x.x.x (a German address)"form": {"via": "residential-premium"}

Headers and body went through unchanged; only the origin changed. Use one session ID for the steps of one form. Gateways, sticky sessions and SOCKS5 are in how to use a proxy with curl; a wrong proxy password shows as 407 Proxy Authentication Required.

Which network for POST jobs

PlanTested here withGood for
Residential Basic--json through residentialboson.quanticdata.io:10000Search and form endpoints that answer differently by country
Residential Premium-d through residentialpremium.quanticdata.io:8080Home IPs in the country you pick, with a session time you set
Mobile--json through mobile.quanticdata.io:8080Requests that should come from a mobile carrier IP

Plans are on the pages for residential proxies and mobile proxies, and there is a Residential Basic free trial. When you would rather get a page back as clean data from one API call, see our web scraping API.

Sources & further reading

FAQ

Quick answers on curl post request.

Something else? Ask us

How do I send a POST request with curl?

Give curl a body: curl -d "name=Ada" URL for form data, curl --json '{"name":"Ada"}' URL for JSON, curl -F "file=@rows.csv" URL for a file. Each one makes the request a POST, so -X POST is not needed.

How do I POST JSON with curl?

Use --json '{"key":"value"}', which also sets Content-Type and Accept to application/json. On an older curl, use -H "Content-Type: application/json" -d '{"key":"value"}'. For long JSON, keep it in a file and send --json @body.json.

Why does my JSON arrive broken when I use curl in PowerShell?

Windows PowerShell 5.1 drops the inner double quotes when it passes the argument to curl.exe: in our test '{"name":"Ada"}' arrived as {name:Ada}. Escape the quotes as \", or put the JSON in a file and send --json '@body.json'.

Do I need -X POST with curl -d?

No. -d, --json and -F already make the request a POST. -X POST on its own sends a POST without a body.

How do I upload a file with a curl POST?

Use -F "file=@path/to/file". curl sends multipart/form-data with the file as a part named file; add more -F name=value options for the other fields of the form.

How do I send a curl POST through a proxy?

Add -x http://HOST:PORT -U "USER:PASS" to the same command. We posted JSON through Residential Basic and Mobile and form data through Residential Premium: the body arrived unchanged and the site saw the proxy IP.

POST from a home or carrier IP

Residential and mobile proxies with country targeting and sticky sessions, ready for curl -x on every request.

Related reading