Using curl to Make REST API Requests

An application programming interface (API) is a set of definitions and protocols that allows software programs to communicate with each other.

The term REST stands for representational state transfer. It is an architectural style that consists of a set of constraints to be used when creating web services.

A RESTful API follows the REST architecture. REST APIs typically use the HTTP protocol for sending and retrieving data and return JSON-formatted responses. You can use the standard HTTP methods to create, view, update, or delete resources through the API.

API requests are made up of four parts:

• Endpoint — The URL the client uses to communicate with the server.
• HTTP method — Tells the server what action the client wants to perform. The most common methods are GET, POST, PUT, PATCH, and DELETE.
• Headers — Pass additional information between the client and server, such as authentication tokens and content type.
• Body — The data sent to the server.

This guide explains how to use curl to interact with RESTful APIs. curl is a command-line utility for transferring data from or to a remote server. It is installed by default on macOS and most Linux distributions.

curl Options #

The syntax of the curl command is:

curl [options] [URL...]

The options used in this guide are:

• -X, --request — The HTTP method to use.
• -i, --include — Include the response headers in the output.
• -sS, --silent --show-error — Hide progress output but still show errors.
• --fail-with-body — Return a non-zero exit code on HTTP errors while still printing the response body.
• -d, --data — The data to send with the request.
• -H, --header — An additional header to send.
• -u, --user — The username and password for Basic authentication.

HTTP GET #

The GET method requests a resource from the server. GET is the default method when making HTTP requests with curl.

The following example sends a GET request to the JSONPlaceholder API and returns a JSON list of all posts:

curl https://jsonplaceholder.typicode.com/posts

To filter results, append query parameters to the URL:

curl https://jsonplaceholder.typicode.com/posts?userId=1

HTTP POST #

The POST method sends data to the server to create a new resource.

The following command sends a POST request with form-encoded data using the -d option:

curl -X POST -d "userId=5&title=Hello World&body=Post body." \
    https://jsonplaceholder.typicode.com/posts

By default, when -d is used without a Content-Type header, curl sends Content-Type: application/x-www-form-urlencoded.

To send JSON data, set the Content-Type header to application/json:

curl -X POST -H "Content-Type: application/json" \
    -d '{"userId": 5, "title": "Hello World", "body": "Post body."}' \
    https://jsonplaceholder.typicode.com/posts

For more examples, see How to Use curl to Make POST Requests .

HTTP PUT #

The PUT method replaces a resource on the server with the data provided in the request body. All fields of the resource are replaced — fields not included in the body are overwritten with null or default values.

curl -X PUT -H "Content-Type: application/json" \
    -d '{"userId": 5, "title": "Hello World", "body": "Post body."}' \
    https://jsonplaceholder.typicode.com/posts/5

HTTP PATCH #

The PATCH method applies partial updates to a resource. Unlike PUT, it only updates the fields included in the request body and leaves all other fields unchanged.

curl -X PATCH -H "Content-Type: application/json" \
    -d '{"title": "Hello Universe"}' \
    https://jsonplaceholder.typicode.com/posts/5

HTTP DELETE #

The DELETE method removes the specified resource from the server.

curl -X DELETE https://jsonplaceholder.typicode.com/posts/5

Authentication #

Most APIs require authentication. curl supports several common authentication methods.

Bearer Token #

Bearer token authentication is used by OAuth 2.0 APIs. Pass the token in the Authorization header:

curl -H "Authorization: Bearer {ACCESS_TOKEN}" \
    https://jsonplaceholder.typicode.com/posts

Basic Authentication #

For APIs that use HTTP Basic authentication, pass the username and password with the -u option:

curl -u username:password https://api.example.com/data

curl encodes the credentials and sends them in the Authorization header automatically.

API Key #

Some APIs accept an API key as a custom header:

curl -H "X-API-Key: {API_KEY}" https://api.example.com/data

Other APIs expect the key as a query parameter:

curl "https://api.example.com/data?api_key={API_KEY}"

Inspecting Responses #

Use the -i flag to include the HTTP response status line and headers in the output:

curl -i https://jsonplaceholder.typicode.com/posts/1

HTTP/2 200
content-type: application/json; charset=utf-8
...

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere...",
  "body": "quia et suscipit..."
}

To pretty-print a JSON response, pipe the output to python3:

curl -s https://jsonplaceholder.typicode.com/posts/1 | python3 -m json.tool

If you have jq installed, it provides color-highlighted formatted output:

curl -s https://jsonplaceholder.typicode.com/posts/1 | jq

For automation scripts and CI checks, you can make failures explicit:

curl -sS --fail-with-body https://jsonplaceholder.typicode.com/posts/1

Quick Reference #

For a printable quick reference, see the curl cheatsheet .

Troubleshooting #

SSL certificate problem: unable to get local issuer certificate
The server is using a self-signed or untrusted certificate. In a controlled test environment where you trust the host, add -k to skip certificate verification. Do not use -k against untrusted or production servers.

401 Unauthorized or 403 Forbidden
Your authentication credentials are missing, incorrect, or expired. Verify the token or API key and check the API documentation for the correct header name and format.

Connection refused
The server is not reachable on the specified host and port. Confirm the endpoint URL is correct and that the server is running.

Response is not valid JSON
The server may be returning an error page in HTML. Use -i to inspect the full response including the status code and headers to diagnose the issue.

curl: (6) Could not resolve host
The hostname cannot be resolved. Check the URL for typos and verify the host is reachable.

FAQ #

What is the difference between PUT and PATCH?
PUT replaces the entire resource with the data in the request body. Any field not included in the body is overwritten with a null or default value. PATCH only updates the fields included in the request body and leaves all other fields unchanged. Use PATCH when you want to make a partial update.

Do I always need to specify -X GET?
No. GET is the default method in curl. You only need the -X flag when using POST, PUT, PATCH, DELETE, or other non-GET methods.

How do I send multiple headers?
Repeat the -H flag for each header:

curl -H "Authorization: Bearer TOKEN" -H "Accept: application/json" URL

How do I save the API response to a file?
Use the -o flag to write the output to a file:

curl -o response.json https://jsonplaceholder.typicode.com/posts/1

Conclusion #

You now know how to use curl to make GET, POST, PUT, PATCH, and DELETE requests to REST APIs from the command line. Use the -i flag to inspect response headers when debugging, and add the appropriate authentication header as required by the API.

For more curl examples and options, see the curl Command in Linux guide.

If you have any questions, feel free to leave a comment below.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page