Table of Contents
What is cURL — in very simple terms
Why programmers need cURL
Making your first request
Understanding request and response
Using cURL to talk to APIs
Common mistakes beginners make
01 — Foundations - What is cURL?
Before we talk about cURL, let's talk about servers. When you open a browser and type google.com, your browser quietly sends a message to Google's computer (the server) saying: "Hey, give me your homepage." The server reads your message and sends back the page.
That whole exchange is called an HTTP request and response. Your browser handles all of this automatically — you never see it happening.
Now, what if you want to send that same kind of message without a browser? What if you're writing code, testing an API, or debugging a server? That's exactly where cURL comes in.What is cURL?
Before we talk about cURL, let's talk about servers. When you open a browser and type google.com, your browser quietly sends a message to Google's computer (the server) saying: "Hey, give me your homepage." The server reads your message and sends back the page.
That whole exchange is called an HTTP request and response. Your browser handles all of this automatically — you never see it happening.
Now, what if you want to send that same kind of message without a browser? What if you're writing code, testing an API, or debugging a server? That's exactly where cURL comes in.
💡 Simple DefinitioncURL (short for Client URL) is a command-line tool that lets you send HTTP requests directly from your terminal. Think of it as a browser without a screen — it talks to servers and shows you what comes back.
cURL was created in 1998 and is installed by default on macOS, Linux, and modern Windows. You don't need to install anything to get started.
The key takeaway: a browser and cURL are doing the exact same thing — sending HTTP requests to a server. The browser just draws a pretty interface around the response. cURL shows you the raw data.
02 — Motivation - Why Programmers Need cURL
You might wonder: if a browser already does all this, why would anyone use cURL? The answer is that when you're building software, you often need to communicate with servers in ways a browser wasn't designed for.
Here's when cURL shines:
Imagine you're building a weather app. Your app talks to a weather API. Before writing any code, you want to just check — does the API work? Does it return what I expect? cURL lets you verify this in seconds from the terminal, without writing a single line of JavaScript or Python.
🎯 | Where cURL fits in developmentcURL sits between you and the server. It's your direct line of communication — no app, no framework, no middleman. That's exactly what makes it so powerful for testing and debugging. |
03 — Hands On - Making Your First Request
Open your terminal (Terminal on macOS/Linux, PowerShell or CMD on Windows) and type this:
curl https://example.com
That's it. Hit Enter. You'll see a bunch of HTML printed in your terminal — that's the source code of example.com, the same thing your browser would receive and then render as a visual page.
Let's try something more interesting. There's a free test API called JSONPlaceholder that returns fake data. Try this:
curl https://jsonplaceholder.typicode.com/posts/1
You should see something like this:
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat...",
"body": "quia et suscipit..."
}
Congratulations — you just made your first API request! That's real data fetched from a real server, using nothing but cURL.
04 — Core Concepts - Understanding Request & Response
Every time cURL talks to a server, two things happen: a request goes out, and a response comes back. Understanding this pair is the foundation of everything in web development.
The most important thing in a response is the status code. Here are the ones you'll see constantly:
200 OK → Everything worked fine
201 Created → A new resource was created (common after POST)
301 Moved → This URL has moved somewhere else
400 Bad Request → Your request had an error
401 Unauthorized → You need to log in or provide a token
404 Not Found → The resource doesn't exist
500 Server Error → Something broke on the server's end
Want to see the full response headers in cURL? Add the -i flag:
curl -i https://jsonplaceholder.typicode.com/posts/1
📌 One flag at a time
We won't overwhelm you with flags. As you need them, you'll naturally pick them up. For now, the most useful ones to know are -i (show headers) and -v (verbose, shows everything).
05 — Real World - Using cURL to Talk to APIs
Most APIs support at least two types of requests: GET (to fetch data) and POST (to send data). Let's look at both.
GET — Fetching Data
A GET request asks the server to give you something. You've already done this! Here's another example — fetching a list of posts:
# Fetch all posts
curl https://jsonplaceholder.typicode.com/posts
# Fetch just post number 5
curl https://jsonplaceholder.typicode.com/posts/5
POST — Sending Data
A POST request sends data to the server — like submitting a form, creating a new record, or logging in. You need to tell cURL two things: that it's a POST request, and what data to send.
curl -X POST https://jsonplaceholder.typicode.com/posts \
-H "Content-Type: application/json" \
-d '{"title": "My First Post", "body": "Hello world!", "userId": 1}'
Let's break that down:
-X POST → tells cURL to use the POST method
-H "..." → adds a header (here we say we're sending JSON)
-d '...' → the data (body) you're sending to the server
✅ Start with GET, then try POSTWhen exploring a new API, always start with GET requests. They're read-only, so nothing can break. Once you understand what the API returns, move on to POST or other methods.
Here's a real-world flow: imagine you're building a to-do app and the backend is running locally on your machine. You'd test it like this:
# Check if your local server is running
curl http://localhost:3000/todos
# Add a new to-do item
curl -X POST http://localhost:3000/todos \
-H "Content-Type: application/json" \
-d '{"task": "Learn cURL", "done": false}'
This is exactly how backend developers test their APIs every day, before wiring them up to a frontend.
06 — Watch Out For Common Mistakes Beginners Make
Everyone makes these mistakes when starting out. Here's how to spot and fix them quickly.
1. Forgetting https://
❌ curl api.example.com/data
✅ curl https://api.example.com/data
Without the protocol, cURL may not know how to connect, or may use a default that doesn't work.
2. Wrong quotes in Windows CMD
❌ curl -d '{"name": "Alice"}'
✅ curl -d "{\"name\": \"Alice\"}"
Single quotes work in macOS/Linux terminals. In Windows Command Prompt, you need double quotes and must escape the inner ones.
3. Missing Content-Type for JSON
❌ curl -X POST -d '{"name":"Alice"}' https://api.example.com
✅ curl -X POST -H "Content-Type: application/json" -d '{"name":"Alice"}' https://api.example.com
Without the Content-Type header, the server may not know to parse your data as JSON and will reject or misread it.
4. Ignoring status code
❌ curl https://api.example.com/data
✅ curl -i https://api.example.com/data
If cURL returns nothing or an error, the first thing to check is the HTTP status code. It almost always tells you exactly what went wrong.
5. Too many flags
❌ curl -X GET -H "Accept: */*" -v ...
✅ curl https://api.example.com/data
cURL has dozens of flags. You don't need them upfront. Start minimal — add flags one at a time only when you have a specific need.
💡
Never paste API keys in public cURL commands with API keys are often shared in Stack Overflow answers or chat logs. Always replace real keys with placeholders like YOUR_API_KEY before sharing your commands publicly.
Quick Reference - cURL Commands at a Glance
# Basic GET request
curl https://api.example.com/users
# GET with response headers
curl -i https://api.example.com/users
# POST with JSON body
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "Alice"}' \
https://api.example.com/users
# GET with an API key header
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.example.com/profile
# Verbose mode (see everything)
curl -v https://api.example.com/users
You now know enough cURL to fetch data, test APIs, and debug servers.
The best next step? Pick any public API and start exploring with nothing but your terminal.
