cURL: Sending Data or JSON with cURL POST Requests

Mastering the cURL POST

Introduction

Sending data to an API shouldn't feel like a chore. Whether you are testing a new endpoint, automating a workflow, or debugging a remote server, cURL is the industry-standard tool for the job. It’s a powerful command-line utility used to transfer data across various network protocols, and it remains a staple in every developer's toolkit due to its reliability and ubiquity across Linux, macOS, and Windows.

cURL — is a versatile command-line tool and library used for transferring data to or from a server using various network protocols, most commonly employed by developers to interact with APIs via HTTP and HTTPS.

At its core, cURL (Client URL) acts as a bridge between your terminal and a web server. While it supports everything from FTP to SMTP, its most common use case today is interacting with RESTful APIs. When you need to "create" or "update" a resource on a server, you typically use a POST request. Unlike a GET request, which retrieves data, a POST request carries a payload — in this case, a JSON object — within the body of the message to tell the server exactly what to do.

In a typical development workflow, you'll use cURL to simulate how a frontend application or a mobile app interacts with your backend. By sending a JSON-formatted string along with the correct headers, you can instantly verify if your server is processing data correctly, handling authentication, or returning the expected status codes. It’s the fastest way to "smoke test" an interface without writing a single line of boilerplate code.

Example: Sending a Simple POST Request with cURL

curl -X POST "https://mywebsite.com" \
-d "login=test_user" \
-d "password=this_is_password" \
-d "redirect=mypage"

This specific cURL command sends a POST request to a website using URL-encoded form data (the default format for HTML forms) rather than JSON.

Here is the breakdown of each component:

curl: Invokes the command-line tool to start the network request.
-X POST: Explicitly tells cURL to use the POST method, indicating you are sending data to the server.
"https://mywebsite.com": The destination URL (endpoint) where the data is being sent.
-d "...": The "data" flag. Each -d represents a key-value pair. In this example, it sends three fields: login, password, and redirect.

In this case, cURL command sends data as application/x-www-form-urlencoded

Example: Sending a Simple POST Request with cURL with an authentication (htaccess)

curl -X POST "https://mywebsite.com" \
-u "username:password" \
-d "login=test_user" \
-d "password=this_is_password" \
-d "redirect=mypage"

#or

curl -X POST "https://mywebsite.com" \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQr" \
-d "login=test_user" \
-d "password=this_is_password" \
-d "redirect=mypage"

#or

curl -X POST "https://mywebsite.com" \
-u "username" \
-d "login=test_user" \
-d "password=this_is_password" \
-d "redirect=mypage"

When you need to access a site or API protected by .htaccess (Basic Authentication), you have to provide a username and password. cURL makes this easy with a dedicated flag that handles the encoding for you.

Using the -u Flag (Recommended)
This is the cleanest method. cURL automatically encodes these credentials into a Base64 string and adds the Authorization: Basic header for you.

or

If you prefer to see exactly what is happening under the hood, you can pass the header yourself. Note that the string after Basic must be the Base64 encoded version of username:password or ask an user to enter a password

Example: Sending a Simple POST Request(JSON) with cURL

curl -X POST https://mywebsite.com/v1/api \
-H "Content-Type: application/json" \
-d '{"name": "Jane Doe","email": "jane@example.com","role": "admin"}'

#or
#Json payload can be collected from a file.

curl -X POST https://mywebsite.com/v1/api \
-H "Content-Type: application/json" \
-d @data.json

To send JSON data, you must include a specific header (-H) to tell the server to interpret the data as JSON rather than plain text or a standard form.

Breakdown of the flags:

-X POST: Sets the HTTP method to POST.
-H "Content-Type: application/json": This is the most critical part; it informs the server that the payload is JSON.
-d: Stands for "data." This is where you place your JSON string. Note the use of single quotes around the entire JSON block to prevent the terminal from misinterpreting the double quotes inside.

To make your cURL commands more powerful—especially when debugging or working with secure APIs—you should know these essential flags. These turn a basic request into a professional diagnostic tool.

Parameter	What it does	Why use it?
`-i`	Include Protocol Headers	Shows the server's response headers alongside the data.
`-v`	Verbose Mode	The "debug" flag; shows the full handshake and SSL details.
`-H`	Header	Adds custom headers like Content-Type or Authorization.
`-L`	Follow Redirects	Automatically follows 301/302 redirects to the new URL.
`-k`	Insecure	Connects to sites with "invalid" or self-signed SSL certificates.
`-o`	Output	Saves the server response to a file instead of the terminal.

Advanced cURL Usage Example (JSON)

curl -v -L -X POST "https://api.mywebsite.com/v1/login" \
-u "admin:secret123" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"action": "sync", "force": true}' \
-o response.json

This command is a high-level "power user" example that combines authentication, data transmission, and debugging into a single line. It is a perfect template for testing secure production APIs.

The Request Configuration

curl -v (Verbose): The most important flag for debugging. It outputs the "conversation" between your computer and the server, including the SSL handshake and the exact headers you sent.
-L (Location): Tells cURL that if the API endpoint has moved (a 301 or 302 redirect), it should automatically follow the new link instead of stopping.
-X POST: Defines the HTTP method. Since we are sending data to "login" and "sync," we use POST.

Authentication & Headers

-u "admin:secret123" (User): This handles Basic Authentication. cURL takes these credentials, encodes them in Base64, and automatically adds the Authorization: Basic ... header.
-H "Content-Type: application/json": Tells the server: "The data I am sending you is formatted as JSON."
-H "Accept: application/json": Tells the server: "I want the response you send back to be in JSON format."

Data & Output

-d '{"action": "sync", "force": true}': This is the JSON payload. It tells the API exactly what action to perform.
-o response.json (Output): Instead of flooding your terminal screen with a long JSON response, this saves the server's reply directly into a file named response.json.

Summary

Mastering the cURL POST

This guide explores how to efficiently send JSON payloads to REST APIs using the cURL command-line tool. By leveraging the -X POST method and defining the Content-Type: application/json header, developers can interact with web services directly from their terminal to test endpoints, automate data entry, and debug server responses.

Key takeaways include:

The Command Structure: Using the -d (data) flag to pass your JSON.
Essential Headers: Why the server needs the application/json declaration to parse your request correctly.
Real-World Utility: How cURL serves as a lightweight alternative to GUI tools like Postman for rapid API validation.