How to Build a cURL POST Request with a JSON Body
Construct a reproducible cURL JSON request, quote POSIX shell arguments and keep headers, method and body behavior explicit.
A short cURL command is often the fastest way to share a reproducible API request. It also passes through two independent parsers: your shell first, then cURL. JSON punctuation, apostrophes in values and special URL characters can therefore break an otherwise valid example. Build the command from explicit arguments, keep the intended shell in mind and review the final request before running it.
Specify the URL, headers and payload deliberately
For a JSON API example, provide the target HTTP method, an absolute URL, a Content-Type header when appropriate, and the exact JSON text you want to send. A header does not validate or transform the body into JSON. Check the body independently before testing the API. Our builder accepts headers as a JSON object of string values and puts the body in a raw-data argument. It generates a command only; it does not contact the URL or reveal how the server will respond.
Quote for the shell that will run the command
POSIX single quotes protect most characters from shell expansion. A literal apostrophe requires ending the quoted segment, emitting that apostrophe through a different quoted segment and resuming the original quoting. This detail matters for names such as O’Connor when an ASCII apostrophe is present. The generated command targets shells such as sh and bash. PowerShell and Windows cmd have different parsing rules, so do not assume that a command copied from a POSIX example is directly portable.
Know why raw data and explicit URL options help
A data-raw argument avoids interpreting a leading at sign as a filename. The globoff option prevents cURL from treating braces or square brackets in the URL as URL-globbing patterns. An explicit URL option also makes the argument’s purpose clear. These choices improve reproducibility without making an arbitrary request safe to run. Commands can contain credentials in headers or bodies and can change remote data. Keep real tokens out of documentation and terminal history, and use a nonproduction endpoint for experiments when possible.
Worked example
curl --globoff --request 'POST' --url 'https://example.com/api/users' --header 'Content-Type: application/json' --data-raw '{"name":"Ada"}'Does Content-Type: application/json make an invalid body valid JSON?
No. It declares the representation type. You must still construct valid JSON and satisfy the receiving API’s schema.
Reference and further reading
KEEP EXPLORING
Another useful idea.
How to Flatten Nested JSON Without Losing Structure
Flatten nested JSON for exports and debugging while preserving arrays, empty containers, and keys that contain dots.
JSON Pointer Explained: Paths, Arrays and Escaped Keys
Learn JSON Pointer syntax, including /0 array indexes, ~0 and ~1 escaping, and the empty root pointer.
JSON vs NDJSON: When to Use JSON Lines
Compare JSON arrays and newline-delimited JSON for logs, streaming APIs, exports, and incremental processing.