curl POST request examples: JSON, auth, file upload, and debugging flags

curl is a command-line tool for transferring data using URL syntax, supporting HTTP, HTTPS, FTP, and dozens of other protocols. For API testing and scripting, its HTTP capabilities are most relevant. Understanding how curl constructs a request body is essential for getting the server to receive exactly what you intend.

The -d flag attaches a request body and automatically sets the HTTP method to POST. It accepts three input forms. A plain string like -d '{"key":"value"}' sends the string as the body. A string prefixed with @ like -d @payload.json reads the file content as the body. The special form -d @- reads from standard input, which is useful for piping data into curl.

Critically, -d does not set a Content-Type header automatically. Without Content-Type: application/json, many servers parse the body as application/x-www-form-urlencoded, which is the browser form submission format. A JSON body parsed as form data produces a request with one field whose name is the entire JSON string, which is not what the server expects. Always set -H "Content-Type: application/json" explicitly when sending JSON.

Curl 7.82 introduced the --json flag, which is a shortcut for -H "Content-Type: application/json" -H "Accept: application/json" -d. This covers the most common API testing pattern in a single flag. Check your curl version with curl --version before relying on it, as versions before 7.82 will reject the flag as unknown.

The -F flag is for multipart/form-data, which is used for file uploads and HTML form submissions. Each -F field adds a form part. The value @filename uploads a file from disk. Curl sets the Content-Type header to multipart/form-data with a generated boundary string automatically when -F is used. Do not combine -d and -F in the same command; they produce different content types.

For authentication, the standard header is Authorization: Bearer YOUR_TOKEN_HERE. The Authorization header name is case-insensitive in HTTP but curl is case-sensitive in its own -H parsing. Custom header names like Auth, Token, or X-Auth-Token are not recognized by standard server middleware unless the middleware is explicitly configured for them.

Three curl flags provide progressively more diagnostic information. -i includes the response headers before the body in the output. -v includes the full conversation: TLS negotiation details, request headers sent, redirect history, and response headers. -s suppresses the progress meter and is useful in scripts where you want only the response body without curl status output.

The most useful debugging pattern is combining -i with a specific endpoint to see what the server actually received and returned. If the server returns 415 Unsupported Media Type, the Content-Type header is missing or incorrect. If the server returns 401 Unauthorized, the Authorization header is missing or the token is malformed. If the server returns 400 Bad Request, the body is malformed or missing required fields.

For redirect debugging, -v shows each redirect step. Look for a 301 or 302 response followed by the Location header. Notice whether the redirect changes the scheme from http:// to https://, which causes curl to drop the Authorization header by default. Use --location-trusted to preserve headers through redirects only when you trust the redirect target completely.

For TLS issues, -v shows the TLS handshake and the certificate chain. Look for lines starting with SSL connection using to see the negotiated TLS version and cipher suite. Lines starting with Server certificate show the certificate subject and validity dates. If the handshake fails, the error message at the end of the TLS section explains why.

The -w write-out flag extracts specific values from the completed request into a format string. The %{http_code} variable outputs the HTTP status code. The %{time_total} variable outputs the total request duration. The %{size_download} variable outputs the response body size in bytes. Using -o /dev/null -w "%{http_code} %{time_total}" sends the response body to /dev/null and prints only the status code and timing, which is useful for load testing without saving responses.

For testing endpoint behavior before writing application code, /tools/http-request-builder provides a visual interface that constructs the same request that curl would send, making it easy to compare the curl command output with a GUI equivalent.

The most frequent mistake is sending a JSON body without Content-Type: application/json. The fix is a single -H flag: curl -X POST -H "Content-Type: application/json" -d '{...}' URL. For curl 7.82 and later, --json replaces both the header and -d flags with a single argument.

For redirects that drop the POST body, curl's default behavior on a 301 or 302 is to follow the redirect using GET instead of repeating the POST. This is correct HTTP behavior: redirect responses expect the client to resubmit the request to the new location, and browsers always use GET for simplicity. For API calls, avoid redirects by using the final HTTPS URL directly. If you cannot avoid the redirect, -X POST combined with -L forces curl to repeat the POST, but this violates the redirect semantics and may cause duplicate processing.

For retries in shell scripts, --retry N retries on transient network errors up to N times. --retry-delay SECONDS sets the pause between attempts. --retry-all-errors extends retry behavior to HTTP 4xx and 5xx responses, which is appropriate for some idempotent operations but must be used carefully for non-idempotent POST requests that might cause duplicate side effects.

For timeouts, always set both --connect-timeout and --max-time. --connect-timeout applies only to the TCP connection phase. --max-time applies to the entire request including data transfer. Without --max-time, curl can wait indefinitely for a slow server response. In scripts, 10 seconds for connect-timeout and 30 seconds for max-time are reasonable defaults for most APIs.

For Basic authentication, -u username:password is a shortcut that sets the Authorization: Basic header with the Base64-encoded credentials. For Bearer token auth, the shortcut does not exist; you must set the header explicitly with -H "Authorization: Bearer YOUR_TOKEN_HERE".

For compressed responses, --compressed tells curl to send Accept-Encoding: gzip and decompress the response automatically before printing it. Without this flag, a compressed response body appears as binary garbage in the terminal.

JSON quoting behaves differently between Bash and Windows Command Prompt. In Bash, single quotes protect the JSON string from shell expansion: -d '{"key":"value"}' works correctly. In Windows Command Prompt, single quotes are literal characters, not string delimiters. Use double quotes for the outer shell and escape inner double quotes: -d "{\"key\":\"value\"}". PowerShell has its own quoting rules that differ from both.

For large request bodies, avoid putting the JSON directly in the command because it hits shell argument length limits and is hard to read. Write the payload to a file and read it with -d @payload.json. The @ prefix tells curl to read the file content rather than treating the string as the body. The file must exist and be readable; if it does not exist, curl exits with exit code 26 (Read error) with no other indication of the problem.

Stdin piping with -d @- allows other tools to generate the request body dynamically. For example: echo '{"key":"value"}' | curl -X POST -H "Content-Type: application/json" -d @- URL. This is useful when the body is generated by a previous command in a pipeline. The drawback is that curl reads stdin to completion before sending, so this pattern does not work for streaming body generation.

Session cookies require two flags used consistently: -c cookies.txt saves cookies from responses, and -b cookies.txt sends saved cookies with requests. Use both together for endpoints that require a session-based authentication flow: first POST to the login endpoint with -c, then GET or POST authenticated endpoints with -b. The cookie file is a plain text file in Netscape format that curl reads and writes automatically.

On macOS, the system curl may be older than 7.82 and lack the --json flag. Install a newer version with Homebrew: brew install curl. The Homebrew version installs to a different path and may require adding it to PATH before the system curl. Run which curl and curl --version to verify which version is active.

When piping curl output to jq, use -s to suppress the progress meter so that jq receives only the response body. Without -s, jq attempts to parse the progress meter output as JSON and fails.

Using -k or --insecure disables TLS certificate verification. The request appears to succeed because curl stops checking the certificate, but the connection provides no protection against man-in-the-middle attacks. This flag is sometimes used to silence certificate errors in development and then left in place in staging scripts. Always fix the underlying certificate issue rather than disabling verification. In local development, use mkcert to create trusted certificates.

Using -X GET with -d sends a GET request with a request body. Most web servers ignore bodies on GET requests. Some servers, API gateways, and proxies reject GET requests with bodies outright. For data retrieval, use query parameters instead of a request body: curl "https://api.example.com/v1/users?status=active" rather than a GET with a JSON body.

The -L flag follows redirects, which is often what you want. However, -L on a POST request converts the method to GET when following a 301 or 302 redirect. If the redirected endpoint expects a POST, the server returns 404 or 405 Method Not Allowed. For POST-specific redirects, use 307 Temporary Redirect on the server side, which preserves the POST method through the redirect.

Omitting -i means response headers are not printed. When debugging an authentication failure, the response headers often contain the WWW-Authenticate header that explains exactly which authentication scheme is required. Without -i, you see only the 401 body, which may be less informative.

Using --data-raw instead of -d has a specific meaning. --data-raw sends the string exactly as given without any interpretation of @ prefixes or newline stripping. -d strips newlines from the data and reads files when the string starts with @. Use --data-raw when you want a literal @ character in the body or when the body contains newlines that must be preserved.

Not following security guidance for secrets in shell commands is a risk in multi-user environments. Shell commands with secrets in the -d flag or -H flag are visible in shell history and in process listings that other users can read with ps aux. Use environment variables to store tokens and reference them with $TOKEN in curl commands, or read secrets from a file.

Build reliable shell scripts around curl by checking exit codes and HTTP status separately. curl's exit code reflects network and protocol errors, not HTTP status codes. A successful connection to a server that returns 500 exits with code 0. Capture the HTTP status using -w "%{http_code}" and -o to redirect the body to a file: HTTP_STATUS=$(curl -s -o /tmp/response.json -w "%{http_code}" ...). Then check both the exit code with $? and the HTTP status with the captured variable.

Always set timeouts in scripts. Unattended scripts that hang on slow API responses block CI pipelines, scheduled jobs, and deployment scripts indefinitely. Use --connect-timeout 10 --max-time 30 as a baseline and adjust based on the expected response time of each endpoint.

Store secrets in environment variables rather than embedding them in curl commands. Reference them as -H "Authorization: Bearer $API_TOKEN" rather than pasting the token directly. This keeps secrets out of shell history, process listings, and version control. In CI systems, inject secrets as environment variables from a secrets manager.

Use jq to parse and transform JSON responses in shell scripts. curl -s URL | jq '.users[] | select(.active == true) | .email' extracts a filtered list of fields without writing a Python or Node.js script. jq is available in most package managers and can be used with -c for compact output or -r for raw string output that removes JSON string quotes.

For API endpoints that you regularly test, consider using /tools/http-request-builder to build and test the request interactively first, then convert the result to a curl command for scripting. This avoids the iteration cycle of writing a curl command, running it, reading the error, and adjusting flags.

For multipart uploads in scripts, write the file path into the -F flag rather than reading the file content into a variable. curl handles the file reading and boundary generation efficiently. Trying to base64-encode a file and embed it in a JSON body instead of using multipart is a common workaround that works but increases payload size by 33 percent and is less broadly supported by file-handling endpoints.