Guides

How to test an API with curl — 6 commands to find out whose bug it is

Illustration: a test lead plugged straight into the socket, bypassing all the wiring

Your app isn't getting a response from the API. So it begins: a console.log every other line, restarting the server, "maybe I put the await in the wrong place."

Half an hour inside your own code — and only then does it turn out the server was saying "invalid key" the whole time.

There's a way to learn that in thirty seconds. One command in the terminal, bypassing your code entirely.

Why curl, when you can just run the app

Because in an app there are ten layers between you and the server: framework, wrapper, cache, environment variables, your own logic. The bug can be born in any of them — and it looks identical from the outside.

curl strips every layer. It takes an address and knocks directly. What you see is literally what the server said.

Which immediately gives you a fork:

  • curl answers fine → server is alive, key works, the bug is in your code.
  • curl answers with an error → your code is innocent, fix the request or the access.

Nothing to install. curl ships with macOS, Linux and Windows 10+.

Six commands, in order

1. Just knock

curl https://api.github.com/users/torvalds

JSON comes back — you have connectivity. Silence or a network error, and there's no point going further; the problem isn't in your code.

2. Look at the headers, not just the body

curl -i https://api.github.com/users/torvalds

The -i flag mixes the service part into the response. That's where the useful stuff lives: the status code (HTTP/2 200), rate limits (x-ratelimit-remaining) and the request id support will ask for when you come complaining.

3. Add the key

The key goes in a header via -H. Just don't type it into the command — put it in an environment variable:

export API_KEY="your-key"
curl -i https://api.openai.com/v1/models -H "Authorization: Bearer $API_KEY"

A 401 means the key wasn't accepted. 403 means it was accepted but lacks permission. Worth telling apart: 401 and 403 are different diagnoses.

4. Send a POST with JSON

The most common request to a model looks like this:

curl -s https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6","messages":[{"role":"user","content":"Say it works"}]}'

Three things people trip over most:

  • -d is the request body. The moment -d shows up, curl switches to POST by itself.
  • The Content-Type: application/json header is mandatory, or the server decides you sent a form.
  • Quotes. Double inside the JSON, single around it. If that keeps biting you, put the body in a file and pass -d @body.json.

5. Check streaming

If the answer is supposed to type itself out letter by letter, add "stream": true to the body and the -N flag to the command:

curl -N -s https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6","stream":true,"messages":[{"role":"user","content":"Count to five"}]}'

-N turns off buffering: without it curl hoards the response and dumps it at once, so you can't tell whether streaming works at all. With it, data: {...} lines start running down the terminal — that's the stream.

6. Get only the status code

When you don't need the body, just the verdict:

curl -s -o /dev/null -w "%{http_code}\n" https://mysite.com

-o /dev/null throws the body away, -w prints only the code. Handy when checking a dozen addresses in a row, or asking "is my service alive after that deploy?"

The trick that saves the most time

You don't have to assemble that long command by hand. The browser will hand it to you.

Open DevTools → the Network tab → do the thing on the page → right-click the request → Copy → Copy as cURL.

Your clipboard now holds the full command with every header, cookie and body — exactly the request the browser sent. Paste it into the terminal and play: drop a header, change a field, run again. That's how you find, in a minute, the one header the server refuses to live without.

The trap: your key ends up in shell history

Everything you type in a terminal settles into a history file. A key typed straight into a command stays there forever — and leaks along with a backup, a screenshot or a screen share.

That's why step three used export API_KEY=...: the command only shows the variable's name. Bonus, you can't accidentally paste the key into a chat or a GitHub issue. The rest of the rules are in how to store API keys safely.

What you end up with

After six commands you're holding this:

  • you know the server's status code — so you know where to look;
  • you've seen a live response and can compare it with what your code expects;
  • you can hand the same command to a colleague or to support — it reproduces anywhere.

The rule from here is simple: curl first, code second. Thirty seconds instead of half an hour.

How is curl different from Postman?

In substance, not at all — both send the same HTTP request. The difference is form: Postman has windows and history, curl is one line you can drop into a chat, a script or CI. For a quick "is the server alive?" curl is usually faster, because there's nothing to open.

Why does curl work while the same request fails from my code?

Then something in the request differs, and your job is to find it. Usually it's headers: your code adds its own, curl doesn't. Second suspect is the body — an object got stringified somewhere in a way you didn't expect. Third, if the request runs in a browser, is CORS: curl ignores it, while the browser cuts the response even when the server answered 200.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →