curl vs Postman compared

The curl flags worth knowing

Most API work needs about eight of them:

# status code only — the fastest health check there is
curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/health

# full timing breakdown: DNS, TCP, TLS, first byte, total
curl -s -o /dev/null -w 'dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  https://api.example.com/v1/orders

# what actually went over the wire, headers and TLS handshake included
curl -v https://api.example.com/v1/orders

# a POST with auth and a JSON body
curl -sS -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sku":"A-1","qty":2}'

# fail the shell on a 4xx/5xx instead of printing the error body
curl -sS --fail-with-body https://api.example.com/v1/orders

# response headers only
curl -sI https://api.example.com/v1/orders

# follow redirects, and cap the whole thing so a hung endpoint cannot block CI
curl -sSL --max-time 10 https://api.example.com/v1/orders

Assertions with curl and jq

curl has no assertion syntax, but jq -e exits non-zero when the filter is false or null, which is all a shell script needs:

#!/usr/bin/env bash
set -euo pipefail
API=${1:?usage: smoke.sh https://api.example.com}

# 1. the endpoint requires auth
[ "$(curl -so /dev/null -w '%{http_code}' "$API/v1/orders")" = 401 ] || { echo "FAIL: no auth required"; exit 1; }

# 2. the happy path returns the documented shape
curl -sS --fail-with-body -H "Authorization: Bearer $TOKEN" "$API/v1/orders/42" \
  | jq -e '.id and .sku and (.qty | type == "number") and (.status | IN("pending","paid","shipped"))' \
  >/dev/null || { echo "FAIL: response shape"; exit 1; }

# 3. invalid input is a 4xx, not a 500
code=$(curl -so /dev/null -w '%{http_code}' -X POST "$API/v1/orders" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"qty":-1}')
[ "$code" = 422 ] || { echo "FAIL: validation returned $code"; exit 1; }

echo "smoke passed"

That script runs in any CI image with no install step, which is exactly why curl survives on teams whose day-to-day client is a GUI.

Moving between the two

Both directions are one action:

# Postman -> curl:  right-click a request > Code > cURL, or the "</>" icon.
# The output is a complete, pasteable command including headers and body.

# curl -> Postman:  Import > Raw text, paste the command.

Use the first when a colleague needs to reproduce something without your workspace, and the second when someone sends you a reproduction from a terminal. Keeping both flows in the team's habits removes most of the "works on my machine" traffic around API bugs.

When each one is right

Reach for curl when the thing has to be reproducible or scripted, when you are debugging TLS, redirects, headers or timing, when it belongs in a runbook or a CI step, or when you need an answer in one line with no application open.

Reach for Postman when you are exploring an API you do not know, when you need environments and chained requests without writing shell, when non-engineers need to run something, or when the request set is worth saving and sharing.

Reach for neither as your test suite. Both cover the requests a human wrote. The suite that covers every operation, every declared response code and every schema constraint is generated from the contract:

schemathesis run openapi.yaml --url "$STAGING_URL" --checks all

Keep curl for the runbook, the client for exploration, and the generated suite for the gate.

curl in CI, properly

Most curl-in-CI problems come from the same three omissions: no timeout, no failure on 4xx, and no retry on a genuinely transient error.

#!/usr/bin/env bash
# health-gate.sh — a post-deploy check that behaves in a pipeline
set -euo pipefail
API=${1:?}

curl_json() {
  curl -sS --fail-with-body \
       --max-time 10 \
       --retry 3 --retry-delay 2 --retry-connrefused \
       -H "Authorization: Bearer ${TOKEN:?}" \
       -H 'Content-Type: application/json' \
       "$@"
}

# --retry only retries transient conditions; a 422 will not be retried away
curl_json "$API/v1/orders?limit=1" | jq -e '.items | type == "array"' >/dev/null
echo "ok"

The flags that matter and why:

Debugging with curl when Postman says it works

The classic support case: it works in Postman and fails from the service. Almost always the difference is something Postman added silently.

# what did we actually send? headers, TLS, redirects, the lot
curl -v https://api.example.com/v1/orders -H "Authorization: Bearer $TOKEN" 2>&1 | head -40

byte-level, when a header or encoding is suspect

curl --trace-ascii - -X POST https://api.example.com/v1/orders
-H 'Content-Type: application/json' -d '{"sku":"A-1"}' | head -60

is the TLS chain the problem, or the application?

curl -vI --tlsv1.2 --tls-max 1.2 https://api.example.com 2>&1 | grep -E 'SSL|TLS|subject|issuer'

does it resolve where you think it does?

curl -s -o /dev/null -w 'ip=%{remote_ip} port=%{remote_port}\n' https://api.example.com

The usual culprits, in rough order of frequency: Postman adding an `Accept-Encoding` or `User-Agent` header the service treats differently, a cookie left over from an earlier request in the collection, an environment variable resolving to a stale token, and a proxy configured in the app but not in the service's environment.

Running the same request both ways and diffing the two `-v` outputs settles it in a couple of minutes, which is why "copy as cURL" is the first thing to ask for when someone reports this.

## Making both habits stick on a team

The division of labour only works if it is written down somewhere people read. Three conventions do most of the work.

**Runbooks contain curl, never screenshots.** An incident runbook whose diagnostic step is "open Postman and run the health collection" fails at 3am for the person who does not have the workspace. The same step as a curl one-liner works for everyone, including a future automation.

**Bug reports contain a reproduction command.** Make "copy as cURL" the expected format in the bug template. It removes an entire class of back-and-forth, because the reporter's exact request — headers, body, auth shape — is in the ticket rather than described.

**The collection is generated, not curated.** If the team keeps a shared collection, generate it from the OpenAPI document on a schedule rather than editing it by hand. A curated collection becomes a second contract that disagrees with the first, and nobody can tell which is right.

```bash
# regenerate the shared exploration collection nightly from the spec
npx openapi-to-postmanv2 -s openapi.yaml -o collection.json -p

None of this is about preferring one tool. It is about making sure the artifact that travels between people — a ticket, a runbook, a pipeline step — is the one that works without your machine.

Sources and further reading

• RFC 9110 — HTTP Semantics — the normative definition of the methods, status codes and headers you are asserting on.
• Postman Learning Center — collections, scripts and the code-generation feature.
• OpenAPI Specification — the contract a generated suite is derived from.

Key takeaways

• curl wins on reproducibility, scriptability and debugging; Postman wins on exploration, environments and sharing with people who do not use a terminal.
• -w '%{http_code}', -v, --fail-with-body and the timing format string cover most day-to-day API debugging.
• curl | jq -e is enough to build a real smoke test with no dependencies beyond what is already in the CI image.
• Postman's "Copy as cURL" and curl import make moving between the two a single action — use both routinely to kill "works on my machine".
• Neither is a test suite. Generate that from the OpenAPI document and keep these two for the jobs they are actually good at.

Related articles

How to Use Postman for API Testing | REST API Testing Best Practices | API Testing Checklist | How to Write API Test Cases | 12 Best Postman Alternatives