Curl -d Flag Example

The command

curl -d "name=Ada" -d "role=admin" https://httpbin.org/post

Run this request in the API Tester

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

What the flags do

The three side effects

Giving curl -d changes the method to POST, adds Content-Type: application/x-www-form-urlencoded, and adds a Content-Length. None of that depends on what the data looks like: JSON passed to -d is still announced as a form unless you override the header. Several -d flags are concatenated with & between them, which is handy for forms and wrong for anything else.

To send the same data in the URL of a GET instead, add -G.

curl -d '{"a":1}' -H "Content-Type: application/json" https://httpbin.org/post
curl -G -d "q=curl" -d "page=2" https://httpbin.org/get

Reading from files and stdin

-d @path reads the body from a file and -d @- reads it from standard input. In both cases -d removes carriage returns and newlines. That was designed for form data kept one field per line and it surprises everyone else. --data-binary takes the same @ syntax and changes nothing.

--data-urlencode has its own forms: name=value encodes the value, name@file encodes a file's content as the value, and a bare =value encodes without a name.

curl --data-binary @payload.json -H "Content-Type: application/json" https://httpbin.org/post
echo '{"a":1}' | curl --data-binary @- -H "Content-Type: application/json" https://httpbin.org/post
curl --data-urlencode "comment@message.txt" https://httpbin.org/post
curl --data-raw "@mention goes here" https://httpbin.org/post

Common mistakes

• -d never URL-encodes. A + in a value reaches the server as a space and a stray & starts a new field.
• A value beginning with @, such as a social handle or an email local part, makes -d look for a file. Use --data-raw.
• Large bodies trigger Expect: 100-continue on HTTP/1.1, which adds a pause with servers that ignore it. -H "Expect:" removes it.

Related curl examples

More under Request bodies

• Curl GET JSON Example
• Curl POST File Example
• Curl POST XML Example
• Curl POST Body Example
• Curl JSON Request Example
• Curl GET XML Example

References

• curl man page: -d — The full description of --data and its file syntax.
• curl man page: --data-urlencode — The variant that percent-encodes values.
• curl man page: --data-binary — The variant that leaves newlines alone.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ