POST JSON Data With Curl

The short answer

To send a HTTP request with a payload in the JSON format, you can use the [.inline-code]curl[.inline-code] command as follows:

$ curl -X POST -H 'Content-Type: application/json' -d '{"<key>":"<value>", ...}' <url>

Where:

• The [.inline-code]-X[.inline-code] flag is used to set the HTTP method of the request to [.inline-code]POST[.inline-code].
• The [.inline-code]-H[.inline-code] flag is used to set the [.inline-code]Content-Type[.inline-code] header of the HTTP request to [.inline-code]application/json[.inline-code], which corresponds to the JSON media type.
• The [.inline-code]-d[.inline-code] flag is used to specify the payload of the HTTP request.

For example:

$ curl -X POST -H 'Content-Type: application/json' -d '{"email":"user@example.com","password":"helloworld"}' http://example.com/login

Note that as of [.inline-code]curl[.inline-code] version 7.82.0, you can also use the [.inline-code]--json[.inline-code] flag as follows:

$ curl --json '{"<key>":"<value>", ...}' <url>

To learn more about sending HTTP POST requests in general, you can read our other article on how to send POST requests with cURL.

[#easily-recall-syntax-with-ai] Easily retrieve this command using Warp’s AI Command Suggestions [#easily-recall-syntax-with-ai]

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Suggestions feature:

Entering [.inline-code]send json data with curl[.inline-code] in the AI Command Suggestions will prompt a [.inline-code]curl[.inline-code] command that can then be quickly inserted in your shell by doing CMD+ENTER .

[#send-json-from-a-file] Sending a JSON payload from a file [#send-json-from-a-file]

To send JSON data from a file instead of the command-line, you can use the following syntax:

$ curl -X POST -H 'Content-Type: application/json' -d @<file> <url>

Where:

• [.inline-code]file[.inline-code] is the path to the file containing the JSON payload.

For example, this command will send a request with a JSON payload loaded from the file named [.inline-code]data.json[.inline-code] located in the current working directory:

$ curl -X POST -H 'Content-Type: application/json' -d @data.json http://example.com

[#handle-large-json-payloads] Handling large JSON payloads [#handle-large-json-payloads]

To send large JSON payloads as it, without any character conversion or modification, you can use the [.inline-code]--data-binary[.inline-code] flag as follows:

$ curl -X POST -H 'Content-Type: application/json' --data-binary @<file> <url>

Properly formatting the JSON object

[#check-the-json-syntax] Checking the payload format [#check-the-json-syntax]

To make sure that the JSON payload is properly formatted, you can pipe it into the [.inline-code]jq[.inline-code] command as follows:

$ echo '{"<key>":"<value>", ...}' | jq
$ cat <file> | jq

The [.inline-code]jq[.inline-code] command will then parse the data, and either write the JSON object back to the terminal if valid, or output an error message otherwise.

For example:

$ echo '{"hello":"world"}' | jq
{
  "hello": "world"
}
$ echo '{"hello":world}' | jq
jq: parse error: Invalid numeric literal at line 1, column 15

[#escape-special-characters] Escaping special characters in JSON [#escape-special-characters]

In JSON, certain characters such as double quotes ([.inline-code]"[.inline-code]) or backslashes ([.inline-code]\[.inline-code]) need to be escaped to ensure that the data is correctly formatted and parsed. To escape these characters, you can prepend them with a backslash character.

For example, in the following request, the string [.inline-code]h3\o"[.inline-code] needs to be escaped as follows:

$ curl -X POST -H 'Content-Type: application/json' -d '{"email":"user@example.com","password":"h3\\o\""}' http://example.com/login

[#specify-the-data-charset] Specifying the payload’s charset [#specify-the-data-charset]

To prevent encoding issues between the client and the server, you can specify the character set of the HTTP request through the [.inline-code]Content-Type[.inline-code] header as follows:

$ curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d <payload> <url>

[#send-authenticated-requests] Sending authenticated requests [#send-authenticated-requests]

It may sometimes happen that when sending a request to a protected endpoint, the server responds with an HTTP 401 Unauthorized. This means that the request must be authenticated using an access token, usually generated in response to a login request.

To send an authenticated HTTP request containing an access token, you can specify the [.inline-code]Authorization[.inline-code] header as follows:

$ curl -X POST \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{"<key>":"<value>"}' \
<url>

For example:

$ curl -X POST \
-H 'Authorization: Bearer a8JxldMFxA' \
-H 'Content-Type: application/json' \
-d '{"":""}' \
http://example.com/