Guide to using JSON with cURL

cURL is a powerful command-line tool used for making HTTP requests, commonly used for sending and receiving JSON data in APIs. Whether you're working with REST APIs, automation scripts, or debugging requests, understanding how to send JSON data with cURL is essential.

This guide walks you through various ways to work with cURL and JSON, including how to post JSON, send a JSON body, and even upload a JSON file with cURL.

Sending JSON from a File

When you're dealing with structured data, it's often more convenient to save your JSON in a file and send it directly. With cURL, you can do this easily using the @ symbol followed by the filename. This is especially useful for larger payloads or cases where you need to reuse the data in multiple requests.

$ curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d @data.json

Let's break down the cURL command options:

• -X POST: Specifies the HTTP method (POST in this case)
• -H "Content-Type: application/json": Sets the HTTP header indicating that sent data is of JSON type
• -d @data.json: Specifies the data to send where @ tells curl to read the data from a local file instead of a direct string

In the above command, data.json is the file containing the JSON payload. cURL reads the file and sends its contents as the request body. This method is useful for sending large or complex JSON structures without embedding them directly in the command.

Using cURL to post a JSON file keeps your request clean and manageable, making it a great approach for automation scripts and API testing.

Now that we’ve covered sending JSON from a file, let's explore how to send it directly from a string.

Sending JSON from a String

For quick API requests, you can send JSON directly as a string using the -d flag. This method is perfect for smaller payloads or when you’re just testing an API.

$ curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d '{"name": "Alice", "age": 30}'

Here, we specify the JSON data inline within the -d option. This method works well for quick API requests but can become cumbersome with longer JSON structures.

This inline approach makes it easy to post JSON with cURL without needing a separate file, which is handy for debugging and quick interactions with APIs.

Sometimes, JSON is generated dynamically from other commands. Let’s see how that works next.

Sending JSON from Pipe

Piping JSON between commands is a powerful way to dynamically generate, transform, and send data. Here are comprehensive examples demonstrating different piping scenarios:

# Generate JSON with jq and pipe directly to curl
$ echo '{"users": [{"name": "Alice"}, {"name": "Bob"}]}' | jq '.users[0]' | curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d @-

The key points here:

• echo creates initial JSON
• jq filters or transforms the JSON
• curl -d @- reads data from stdin (the pipe)

Sending JSON from Inline Command

Generating JSON dynamically is useful in scripting and automation. A common tool for this is jq, which formats JSON output.

$ curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d "$(jq -n --arg name "Alice" --argjson age 30 '{name: $name, age: $age}')"

Here’s what happens in the command above:

• jq -n starts a new JSON object.
• --arg and --argjson insert variables into the JSON.
• The output of jq is used as the -d parameter for cURL.

This approach is useful when dynamically constructing JSON from scripts or fetching data from other sources.

Now, let’s see how to use environment variables in JSON payloads.

Using Environment Variables in JSON

Using environment variables helps make commands more dynamic and reusable. Here's an example:

$ NAME="Alice"
$ AGE=30
$ curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d "{\"name\": \"$NAME\", \"age\": $AGE}"

In this example $NAME and $AGE are substituted with their values and JSON is passed as a string with embedded variables.

This method is particularly useful in scripts where values change dynamically.

Before sending JSON, it's a good idea to validate it. Let's discuss that next.

Tip: Validate JSON Before Sending

To ensure your JSON is correctly formatted before sending, you can use jq or cURL with httpbin.dev for validation:

$ cat data.json | jq empty

If the JSON is invalid, jq will return an error. Alternatively, test the JSON by making a POST request to https://httpbin.dev/post, which echoes the received data:

$ curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d @data.json

You can chain validation and sending in a single command:

# Validate JSON and send only if valid
$ jq empty data.json && curl -X POST https://httpbin.dev/post \
     -H "Content-Type: application/json" \
     -d @data.json

Validating JSON beforehand helps avoid errors when interacting with APIs.

Now that we've covered validation, let's look at some real-world examples.

Real-Life cURL JSON Examples

Here are practical examples of using cURL with JSON for Google Translate and Slack APIs, showing the correct request format for each service.

Sending JSON to Google Translate API

Google Translate API allows sending JSON to translate text between languages but it requires an api key to use, let's see how we can get it:

1. Go to the Google Cloud Console
2. Create a new project
3. Enable the Translate API
4. Create credentials (API key)
5. Restrict the API key to prevent unauthorized use

After aquiring the api key we can now try the api using cURL

$ curl -X POST "https://translation.googleapis.com/language/translate/v2?key=YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "q": "Hello, how are you?",
       "source": "en",
       "target": "es",
       "format": "text"
     }'

This request translates "Hello, how are you?" from English to Spanish.

Next, let’s see how to send JSON messages to Slack.

Sending JSON to Slack Messages

Slack provides multiple methods to programmatically send messages to channels and users. The two most common approaches are through the Web API using authentication tokens and through Incoming Webhooks.

Sending a Message with API Token

The API approach offers more flexibility with advanced formatting options like blocks, attachments, and interactive elements.

1. Go to Slack API Dashboard
2. Create a new app or select an existing one
3. Go to "OAuth & Permissions"
4. Add necessary scopes (e.g., chat:write)
5. Install the app to your workspace
6. Copy the "Bot User OAuth Token"

# Example with scopes for posting messages
$ curl -X POST https://slack.com/api/chat.postMessage \
     -H "Authorization: Bearer xoxb-your-bot-token" \
     -H "Content-Type: application/json" \
     -d '{
       "channel": "#alerts",
       "text": "🚨 Server is down! Immediate action required."
     }'

Using Slack Webhooks

Webhooks provide a simpler implementation for basic messaging needs without requiring OAuth token management.

1. Go to Slack Incoming Webhooks
2. Choose a channel
3. Click "Add Configuration"
4. Copy the Webhook URL

$ curl -X POST https://hooks.slack.com/services/YOUR/SPECIFIC/WEBHOOK \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Server down! Urgent action required."
     }'

Slack allows sending messages via both API tokens and webhooks. Refer to Slack’s documentation for additional details.

Power Up with Scrapfly

Here's an example of how to POST JSON data to the Scrapfly Python SDK:

from scrapfly import ScrapflyClient, ScrapeConfig, ScrapeApiResponse

scrapfly = ScrapflyClient(key="YOUR SCRAPFLY KEY")
api_response: ScrapeApiResponse = scrapfly.scrape(ScrapeConfig(
     url="https://httpbin.dev/post",
     method="POST"
     headers={"content-type": "application/json"},
     data={"name": "Alice", "age": 30},
     # enable autmatic bot bypass
     asp=True,
     # enable headless browsers?
     # render_js=True
     # customize your proxies?
     country="US",
     proxy_pool="public_residential_pool"
     # and many more features!
))
print(api_response.scrape_result)

cURL Alternatives

cURL is a powerful command-line tool for making HTTP requests, but it’s not always the most user-friendly option. Several alternatives offer better usability or additional features. Here are some top options to consider.

Curlie

Curlie offers cURL’s power with ease of use. It supports both command styles and provides improved default settings for a better developer experience.

Pros:

• Enhanced readability with formatted output
• Works with both cURL and HTTPie syntax
• Useful for quick API testing

Cons:

• Slight learning curve for cURL users
• Not as feature-rich as raw cURL for advanced cases

For more details read our article:

Sending HTTP Requests With Curlie: A better cURL

In this guide, we'll explore Curlie, a better cURL version. We'll start by defining what Curlie is and how it compares to cURL. We'll also go over a step-by-step guide on using and configuring Curlie to send HTTP requests.

Postman

Postman is a GUI-based API testing tool that simplifies complex API interactions. It provides a visual request builder, variable management, and automation features, making it ideal for developers working with APIs.

Pros:

• User-friendly interface
• Excellent for managing API workflows
• Supports automated API testing

Cons:

• Higher system resource usage
• Not suitable for quick terminal-based requests

For more details read our article:

Using API Clients For Web Scraping: Postman

Learn to use API clients for web scraping. Locate hidden requests, manipulate them with Postman, and build efficient API-based web scrapers.

Curl Impersonate

Curl Impersonate is a modified version of cURL designed for web scraping and bypassing anti-bot protections. It mimics browsers like Chrome and Firefox, helping requests appear more legitimate.

Pros:

• Reduces chances of detection when scraping websites
• Supports browser-like TLS and HTTP2 fingerprinting

Cons:

• Requires additional setup
• Not necessary for general use cases

For more details read our article:

Use Curl Impersonate to scrape as Chrome or Firefox

Learn how to prevent TLS fingerprinting by impersonating normal web browser configurations. We'll start by explaining what the Curl Impersonate is, how it works, how to install and use it. Finally, we'll explore using it with Python to avoid web scraping blocking.

Each tool has unique strengths, so the best choice depends on your needs. If you prefer a GUI, Postman might be best. For command-line work, Curlie, or Curl Impersonate are solid choices.

FAQ

Below are quick answers to common questions about sending JSON with cURL.

Summary

In this guide, we covered various ways to send JSON using cURL:

• Sending JSON from a file or inline string using the -d option.
• Setting and using environment variables for dynamic values in curl requests.
• Generating JSON with jq before sending it off.
• Using JQ to validate JSON before sending it.
• Real-world curl JSON post examplers like Google Translate API and Slack messages.

With these techniques, you can confidently send JSON data using cURL in any API workflow.