How to Use cURL for API Requests: Step-by-Step Guide

Key Considerations

• cURL is a fast, scriptable command-line tool for sending requests without relying on a browser or GUI.
• It supports all major HTTP methods, authentication types, headers, file uploads, and session handling.
• With the right syntax and debugging flags, cURL becomes a reliable tool for testing, automation, and troubleshooting API workflows.

cURL (pronounced "curl") is a popular open-source command-line tool used to transfer data between servers and clients. It supports many protocols (HTTP, HTTPS, FTP, etc.) and is commonly used to send network requests directly from the terminal.

In practice, developers often use cURL to send HTTP requests to web services, e.g., to test a web REST API endpoint or interact with a remote server without needing a browser.

In this guide, you'll learn how to use cURL API requests (GET, POST, PUT/PATCH, DELETE) with real examples of adding headers, authentication (Basic and Bearer tokens), sending JSON bodies, and even some troubleshooting tips.

Basic syntax of cURL for API use

The basic syntax of a cURL command is:

    	curl [options] [URL]
  	

When using cURL for APIs, you will often include options (also known as flags) to customize the request. Here are some of the most commonly used options in the context of API calls:

• -X (request method): Specifies the HTTP method/verb (e.g., GET, POST, PUT, DELETE). If not provided, cURL defaults to GET for HTTP URLs. For example, -X POST makes the request a POST.
• -H (header): Adds an HTTP header to the request. You can use this to set custom headers like Content-Type, Accept, or authorization header tokens..
• -d (data): Sends data in the body of a request. This is commonly used with POST or PUT requests to send JSON or form data.
• -u (user authentication): Adds Basic HTTP basic authentication credentials. The syntax is -u username:password.
• -i or -v (inspect response): Use -i to include the HTTP response headers in cURL’s output, which is useful for seeing status codes and headers. Use -v for verbose mode, which prints detailed information about the request and response.

Example: A cURL command combining several of these options might look like this:

    	curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "Alice", "email": "[email protected]"}' \
     https://api.example.com/users
  	

In this command, -X POST specifies the method as POST, the Content-Type header is set to JSON, and the -d flag sends a JSON request body with name and email. When executed, cURL will POST this data to the /users endpoint of the API.

Common cURL commands for API requests

Let's look at how to perform the most common HTTP requests using cURL. We’ll go through GET, adding headers, POST, PUT/PATCH, and DELETE with examples.

GET request example

A simple GET request with cURL requires no extra flags since GET is the default method. You just provide the URL. For example, to fetch a user with ID 1 from a sample API:

    	curl https://api.example.com/users/1
  	

This will send an HTTP GET request to the given URL and print the response (e.g., a JSON representation of the user) to the terminal.

GET with headers

Often, you'll need to include headers with your GET request. For example, to specify the response format or provide an API key. You can use one or multiple custom headers with cURL by repeating the -H flag. For instance:

    	curl -H "Accept: application/json" \
     -H "X-API-Key: 12345" \
     https://api.example.com/data
  	

Here, we added two headers: an Accept: application/json header (to request a JSON response) and a fictional X-API-Key for authentication. The server’s response (headers and body) will be printed out.

POST request with JSON body

Creating or adding data via an API typically uses POST. With cURL, you specify -X POST (if not defaulted by using -d) and include the JSON data with -d. For example:

    	curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"title": "New Item", "value": 42}' \
     https://api.example.com/items
  	

In this example, we set the content type to JSON and include a JSON object in the body. The -d flag sends the data; cURL will also automatically add a Content-Length header and default to Content-Type: application/x-www-form-urlencoded if you don't specify a content type.

PUT/PATCH request example

Updating data on an API typically uses PUT or PATCH. The usage in cURL is similar to POST: specify the method and include data. For a full update, PUT is commonly used, whereas PATCH is used for partial updates. For example, to update a user’s email:

    	curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"email": "[email protected]"}' \
     https://api.example.com/users/123
  	

This sends a JSON payload with the new email to update user 123. We use -X PUT to indicate the request method is PUT.

DELETE request example

To remove or delete a resource via cURL, use the -X DELETE flag with the resource URL. For example:

    	curl -X DELETE https://api.example.com/users/123
  	

This will send an HTTP DELETE request to delete the user with ID 123. Often, no request body or additional headers are needed unless the API requires an auth token or a specific content type.

Using cURL with authentication

Many APIs are protected and require authentication. cURL provides straightforward options to handle common auth schemes.

Basic auth example

Basic authentication uses a username and password encoded in the Authorization header. With cURL, you can use -u username:password to handle this.

For example, if an API endpoint requires basic auth:

    	curl -u admin:secret https://api.example.com/protected/resource
  	

cURL will transform admin:secret into an Authorization: Basic ... header (with the credentials base64-encoded) and include it in the request. This saves you from manually encoding and adding the header.

Bearer token example

Another common scheme is Bearer token authentication (used by OAuth 2.0 and others), where you provide an access token in the header. With cURL, you manually add the header using -H "Authorization: Bearer <token>".

For example:

    	curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://api.example.com/data
  	

This attaches a bearer access token to authorize the request. In practice, you replace YOUR_TOKEN_HERE with the token string provided by the API (often a long JWT or random string). The Authorization: Bearer ... header tells the server you’re sending a token for auth. Remember that the authorization header name and format must exactly match what the API expects.

Advanced cURL API usage

Beyond basic GET/POST calls, cURL offers many options to handle more complex API interactions. Here are a few advanced use cases:

Sending multiple headers

We mentioned earlier that you can include multiple headers by repeating the -H flag. This is useful if you need to send several headers in one request (e.g., multiple tokens or custom fields). For example:

    	curl -H "Authorization: Bearer TOKEN123" \
     -H "User-Agent: MyApp/1.0" \
     -H "Accept-Language: en-US" \
     https://api.example.com/endpoint
  	

In this case, three headers (Authorization, User-Agent, and Accept-Language) are sent together. You just use -H for each header key-value.

Uploading files

Uploading a file to an API (for example, sending an image or document) can be done with cURL’s form options. The easiest way is to use the -F (form) cURL command option to simulate a file upload via multipart/form-data.

For instance, if an API expects a file under a field "file":

    	curl -X POST \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/path/to/localfile.png" \
     https://api.example.com/upload
  	

Here, -F "file=@... tells cURL to attach the local file (localfile.png) as a form field named "file". cURL will automatically format this as a multipart form request (with proper boundaries) and include the necessary headers.

Handling cookies and sessions

If you're interacting with an API that uses cookies for session management (less common for modern APIs, but sometimes for login flows or CSRF tokens), cURL can handle cookies too. Use the -c option (cookie jar) to save cookies and -b (cookie file or string) to send cookies.

For example:

    	# First, login and save cookies
curl -c cookies.txt -X POST -d "user=john&pass=doe" https://api.example.com/login
# Later, use saved cookies in another request
curl -b cookies.txt https://api.example.com/profile
  	

In the first command, -c cookies.txt tells cURL to write any cookies set by the server (in the response) into a file named cookies.txt. In the second command, -b cookies.txt loads those cookies and sends them with the request, allowing you to maintain the session (as if the same client is making both requests).

Follow redirects (-L)

By default, cURL will not follow HTTP redirects; if the API returns a 3xx redirect, cURL will just show the redirect response. Many APIs might not redirect, but some endpoints (or web pages you fetch) might respond with a "Location" header (for example, redirecting from http:// to https://).

To have cURL automatically follow redirects, use the -L (or --location) option:

    	curl -L http://api.example.com/data
  	

If http://api.example.com/data responds with a 301/302 redirect to https://api.example.com/data, the -L flag will make cURL retry the request at the new URL.

Why use cURL over GUI tools (Postman, Insomnia)?

You might wonder why use a command-line tool like cURL when there are GUI tools like Postman or Insomnia for testing APIs. While those tools are user-friendly and great for complex testing and collaboration, cURL has its own advantages:

• Fast and scriptable

cURL is lightweight and runs in the terminal, which makes it very fast to launch and use. There’s no heavy interface to load, and you can fire off a request in seconds. This also means cURL is easy to integrate into scripts and automation.

For example, you can add cURL commands in shell scripts, CI/CD pipelines, or within programming languages, making automated API calls or health checks straightforward.

• Ideal for quick testing

If you just need to test an endpoint or reproduce a request, typing (or copy-pasting) a cURL command is often quicker than using a GUI. In scenarios where you’re SSHed into a server or working in a terminal-only environment, cURL is indispensable for making API requests directly.

Common cURL API errors

When using cURL to interact with APIs, you may run into HTTP errors. Here are a couple of common ones and how to address them, as well as tips for debugging:

• 401 unauthorized

The 401 error message indicates the request lacked valid authentication credentials. In other words, the server did not accept your credentials. This often happens if you forget to include a token or API key, or if the token is wrong/expired.

• 400 bad request

This status indicates the server couldn’t understand your request. In other words, essentially, the client (you) did something wrong. A 400 error message is often returned if you’re making API requests with errors, such as bad syntax in the URL or headers, or an invalid/malformed JSON body.

If you encounter errors like the above, cURL’s debugging options can be extremely helpful. Running cURL with -v (verbose) will print the full request and response details (headers, status codes, and even SSL handshake info) to the terminal.

For even deeper insight, cURL offers the --trace option. Using --trace file.txt will log a full trace of the request and response (including binary data) to the given file. This is like a wire dump of the HTTP transaction and is useful for advanced debugging.

You can also use --trace-ascii to get a human-readable trace on the terminal.

Final thoughts

With these debugging techniques and the step-by-step examples above, you should be well-equipped to use cURL to interact with any REST API. If you’re looking for a place to share your experiences, get insights on how to transfer data with residential proxies, or exchange tips, visit our Discord community. Happy cURLing!