JSON with cURL and HTTP APIs: Complete Guide

cURL is the universal command-line tool for interacting with HTTP APIs, and JSON is the universal data format for those interactions. Together, they form the foundation of API testing, debugging, and automation. This guide covers cURL commands for sending JSON, receiving JSON responses, handling authentication, file uploads, and common API testing patterns. Use our JSON Formatter to format cURL responses and JSON Validator to check request payloads.

Basic JSON Requests with cURL

# GET request with JSON response
curl https://api.example.com/users

# GET with JSON Accept header
curl -H "Accept: application/json" https://api.example.com/users

# POST with JSON body (inline)
curl -X POST https://api.example.com/users   -H "Content-Type: application/json"   -d '{"name": "Alice", "email": "alice@example.com"}'

# POST with JSON body from file
curl -X POST https://api.example.com/users   -H "Content-Type: application/json"   -d @user.json

# PUT (full update)
curl -X PUT https://api.example.com/users/1   -H "Content-Type: application/json"   -d '{"name": "Alice Updated", "email": "alice@example.com"}'

# PATCH (partial update)
curl -X PATCH https://api.example.com/users/1   -H "Content-Type: application/json"   -d '{"name": "Alice Updated"}'

Handling JSON Responses

# Pretty print JSON response (using jq or python)
curl -s https://api.example.com/users | jq '.'
curl -s https://api.example.com/users | python3 -m json.tool

# Extract specific fields
curl -s https://api.example.com/users | jq '.[].name'

# Save response to file
curl -s https://api.example.com/users -o response.json

# Show response headers + body
curl -i https://api.example.com/users

# Only show headers
curl -I https://api.example.com/users

# Silent mode (no progress) + write to file
curl -sS https://api.example.com/users > users.json

Authentication with JSON APIs

# Bearer token (JWT)
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."   https://api.example.com/protected

# Basic auth
curl -u username:password https://api.example.com/login

# API key in header
curl -H "X-API-Key: your-api-key-here" https://api.example.com/data

# API key in query parameter
curl "https://api.example.com/data?api_key=your-api-key-here"

# Cookie-based auth (login first, then use cookie)
curl -c cookies.txt -X POST https://api.example.com/login   -H "Content-Type: application/json"   -d '{"username": "alice", "password": "secret"}'

curl -b cookies.txt https://api.example.com/profile

Advanced cURL Patterns

# Follow redirects
curl -L https://api.example.com/redirect

# Set timeout (in seconds)
curl --connect-timeout 5 --max-time 30 https://api.example.com/slow

# Retry on failure
curl --retry 3 --retry-delay 5 https://api.example.com/unstable

# Verbose output (show request/response details)
curl -v https://api.example.com/users

# Send JSON with compressed request
curl --compressed -H "Content-Type: application/json"   -d @large_payload.json https://api.example.com/process

# Conditional request with ETag
curl -H "If-None-Match: "abc123"" https://api.example.com/users
# Returns 304 Not Modified if unchanged

# Rate limit awareness (check headers)
curl -sI https://api.example.com/api | grep -i ratelimit

File Upload with JSON Metadata

# Upload file with JSON metadata (multipart)
curl -X POST https://api.example.com/upload   -F "file=@document.pdf"   -F "metadata={"description": "Annual report", "tags": ["finance", "2025"]};type=application/json"

# Upload as binary with JSON metadata in header
curl -X POST https://api.example.com/upload   -H "Content-Type: application/pdf"   -H "X-Metadata: {"description": "Annual report"}"   --data-binary @document.pdf

Testing Different Content Types

# JSON API that also accepts XML
curl -H "Accept: application/json" https://api.example.com/data
curl -H "Accept: application/xml" https://api.example.com/data

# JSON API versioning via Accept header
curl -H "Accept: application/vnd.api+json;version=2" https://api.example.com/users

# Check Content-Type of response
curl -sI https://api.example.com/users | grep -i content-type

# Send malformed JSON to test error handling
curl -X POST https://api.example.com/users   -H "Content-Type: application/json"   -d 'invalid json'

# Test with empty body
curl -X POST https://api.example.com/users   -H "Content-Type: application/json"   -d ''

cURL Options Quick Reference

Option	Description	Example
-X	HTTP method	-X POST
-H	Custom header	-H "Content-Type: application/json"
-d	Request body (data)	-d '{"key": "value"}'
-d @file	Request body from file	-d @payload.json
-o	Output to file	-o response.json
-s	Silent mode (no progress)	-s
-S	Show errors in silent mode	-sS
-v	Verbose (request + response details)	-v
-i	Include response headers	-i
-L	Follow redirects	-L
-u	Basic auth	-u user:pass

Next Steps

Format cURL JSON responses with JSON Formatter. Validate request payloads with JSON Validator. Minify large request bodies with JSON Minifier.