Skip to content

How to POST JSON with cURL

cURL can carry a JSON request body in a POST without extra plumbing.

OUTPUT FORMATSHTMLJSONMarkdown

On cURL 7.82.0 and later, the --json option does the whole job: it sends the body, switches the method to POST, and sets Content-Type: application/json together with Accept: application/json. Older builds need the -H and -d pair instead. The choice between inline and file payloads is independent of that version question, and the two paths differ in one small but real way: how the body is read from disk.

Pick the flag set that matches your cURL version

Before writing the command, check which cURL you have. The --json option exists only from 7.82.0 onward. If your build predates that, use -H "Content-Type: application/json" together with -d. Both approaches deliver a valid JSON body; the difference is in what cURL fills in for you.

Use this quick decision list:

  • cURL 7.82.0 or newer, short payload → --json with the JSON inline.
  • cURL 7.82.0 or newer, long or complex payload → --json @file.json.
  • Older cURL, short payload → -H plus -d with the JSON inline.
  • Older cURL, long or complex payload → -H plus -d @file.json.

One behavior is worth flagging up front. -d sets only the content type you pass with -H; it does not add an Accept header, so the server sees "Accept": "*/*" in the echoed request. --json sets both headers automatically. If a server varies its response by Accept, that gap matters.

Inline JSON on a modern cURL

When the payload is short enough to type into the terminal, pass it straight after --json. The example below sends a name and age to the hosted HTTPBin endpoint. Because request data is present, cURL selects POST on its own — no -X POST needed.

After the call, the response echoes the parsed payload in its json field, and the headers section shows the JSON content and accept headers that cURL added. That echo is the simplest way to confirm the server actually parsed your body rather than receiving a string it could not decode.

Inline JSON on older cURL

On a build without --json, spell out the content type with -H and hand the body to -d. The two flags split the work: -H sets the request content type to JSON, and -d supplies the body. The response returns the submitted values, so you can verify the round trip the same way as above.

Remember the Accept consequence from the checklist: this form leaves Accept at */*, which is visible in the echoed request headers.

Reading the body from a file

Once the payload grows past a comfortable one-liner, move it into a file — here data.json holding the same name and age object — and point cURL at it with @data.json. On 7.82.0+ that means --json @data.json. On older builds it means -H "Content-Type: application/json" combined with -d @data.json.

The two paths treat whitespace differently. -d strips newlines from the file, while --json transmits the file contents unchanged. Both still produce a valid JSON body, and the server parses them the same way, so the difference is cosmetic for most APIs — but it can matter if you are comparing raw request logs or hashing the body.

What each flag controls

A compact map of the moving parts, drawn from the behavior described above:

  • --json <value> — sends <value> as the body, selects POST, sets Content-Type: application/json and Accept: application/json.
  • --json @file — same as above, but the body is read from the file unchanged.
  • -H "Content-Type: application/json" — sets the request content type; adds nothing else.
  • -d <value> — supplies the request body; does not add an Accept header.
  • -d @file — supplies the body from a file with newlines stripped.

If your server validates Accept, prefer --json where available. If you must support older cURL, add an explicit Accept header alongside -H if the endpoint requires it.

Related cURL tasks

Other common cURL operations pair naturally with JSON posting: sending a GET request, adding Basic Auth credentials, downloading a file, following redirects, retrieving JSON or XML responses, ignoring invalid and self-signed certificates, sending a DELETE request, and setting HTTP headers. A broader walkthrough of web scraping with cURL is also available for readers moving from single requests to collection workflows.

Frequently asked questions

Do I need to add -X POST when using --json?

No. Supplying request data makes cURL choose POST automatically, so -X POST is redundant with --json.

Why does my request show Accept: */* instead of application/json?

That happens when you use -H with -d. -d sets only the content type you pass with -H and does not add an Accept header. --json sets both Content-Type and Accept to application/json.

Does --json @file.json change the file contents?

No. --json sends the file contents as they are. The -d @file form strips newlines from the file. Both remain valid JSON and are parsed identically by the server.

Which cURL version introduced --json?

--json was added in cURL 7.82.0. On earlier builds, use -H "Content-Type: application/json" with -d.

curl --json '{"name":"John","age":30}' \
 {{HTTPBIN_BASE_URL}}/post
curl -H "Content-Type: application/json" \
 -d '{"name":"John","age":30}' \
 {{HTTPBIN_BASE_URL}}/post
{
 "name": "John",
 "age": 30
}
curl --json @data.json \
 {{HTTPBIN_BASE_URL}}/post
curl -H "Content-Type: application/json" \
 -d @data.json \
 {{HTTPBIN_BASE_URL}}/post