Be honest: how many times have you searched "curl post json example"? Not because curl is hard — because its flags live in the exact memory slot your brain garbage-collects first. Single letters, similar meanings, punished harshly for typos. A cURL command builder ends the loop: pick the method, add headers and body in a form, copy a correct command. This guide covers why curl is still the one tool every developer shares, the ten flags that cover 95% of usage, and the quoting traps that quietly eat afternoons.
Curl has been shipping since 1998 and sits preinstalled on effectively every machine that matters — macOS, Linux, and yes, Windows 10+ ships a real curl.exe. That ubiquity made it the lingua franca of HTTP: every API's docs give you a curl example, every bug report worth reading includes the curl command that reproduces it, every CI health check is one line of curl away. GUI clients come and go, install accounts, sync your collections to their cloud. Curl is a string you paste. Strings win.
-X sets the method (-X POST, -X DELETE) — though if you send a body, POST is already implied. -H adds a header; repeat it per header. -d sends the body — and silently sets the content type to application/x-www-form-urlencoded, which is the root of the most common curl bug (next section). -F does multipart form uploads (-F "[email protected]"). -u user:pass handles basic auth. -L follows redirects — without it you're staring at a 301 page wondering where your data went. -i prints the response headers with the body; -v shows the whole conversation, both directions, TLS handshake included — your first move when anything's weird. -o file saves output. -s silences the progress bar for scripts.
Modern bonus: recent curl ships --json '{...}', which sets both JSON headers and the body in one flag. If your curl is new enough, it deletes half of this section.
You POST JSON to an API and get a 400, or worse, a misparse. The command looks right:
curl -X POST https://api.example.com/users -d '{"name": "Ahmad"}'
The bug: no Content-Type: application/json header, so the server was told this is form data. The server-side error rarely says that; it says something baffling about a missing field. The correct version needs -H "Content-Type: application/json" — every time, forever, which is exactly the kind of boilerplate a command builder never forgets.
The second trap is quoting. On bash, single-quote the JSON and you're safe. On Windows cmd, single quotes aren't quotes at all — you need double quotes outside and escaped \" inside, and PowerShell has its own third set of rules where curl is historically an alias for Invoke-WebRequest. The same command genuinely behaves differently in three shells on one laptop. When a paste-from-docs command fails mysteriously, suspect the shell before the API.
The move that solves most "why does this request fail in my code but work in the browser" mysteries: get the working request as curl (every browser devtools has "Copy as cURL" on any network request), get your failing request as curl, run both with -v, and diff. The difference — a missing cookie, an auth header, a user-agent check — is your bug, in plain text, in about ninety seconds. Read the status codes as you go (the field guide), and once the request works, port it into the API tester for repeatable checks — or point it at your own endpoint with the webhook tester when you're on the receiving side.
Every curl command you keep is a small automation: the health check in cron, the deploy hook in CI, the API smoke test before release. The natural next step is agents that compose and run these calls themselves — check the endpoint, parse the response, retry on 5xx, alert on the anomaly. That's the layer QADIR OS provides: local-first agents with HTTP tooling, running scheduled jobs on your machine, with your API keys staying in your environment instead of a cloud runner's secrets vault.
Build the command once, correctly. The free cURL command builder writes methods, headers, auth, and JSON bodies visually — copy and run. Pair it with the API tester for live checks, or join early access for agents that run the whole loop. No card required.