POST JSON Data With Curl

The short answer

To send a HTTP request with a payload in the JSON format, you can use the curl command as follows:

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

Where:

• The -X flag is used to set the HTTP method of the request to POST.
• The -H flag is used to set the Content-Type header of the HTTP request to application/json, which corresponds to the JSON media type.
• The -d 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 curl version 7.82.0, you can also use the --json 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 retrieve this command using Warp’s AI Command Suggestions

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

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

Sending a JSON payload 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:

• file 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 data.json located in the current working directory:

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

Handling large JSON payloads

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

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

Properly formatting the JSON object

Checking the payload format

To make sure that the JSON payload is properly formatted, you can pipe it into the jq command as follows:

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

The jq 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

Escaping special characters in JSON

In JSON, certain characters such as double quotes (") or backslashes (\) 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 h3\o" 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

Specifying the payload’s charset

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

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

Sending 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 Authorization 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/