How to Use cURL PUT Requests

GET and POST requests are frequently used to retrieve and create data. However, the PUT method, though less commonly mentioned, plays a crucial role in updating existing resources. In this article, we’ll provide a clear overview of cURL PUT requests, including syntax, explore the differences between PUT and POST requests, and look over practical examples such as sending JSON data for requests and their expected output.

What is cURL?

The cURL client is an open-source command line tool for getting or sending data using URLs, making it a popular choice among developers. The name cURL stands for “Client URL.” It’s versatile, available on virtually every operating system, easy to use, runs directly in the terminal, and is script-friendly. cURL is a standard tool to do the following:

• Perform API testing: You can use cURL to test APIs by sending requests to various endpoints by creating the POST, GET, PUT, or DELETE requests to check responses.

• Download files: You can download files, such as installation scripts, archives, or any other resource on the web, from a URL directly to your machine.

• Implement automation and scripting: You can integrate cURL into shell scripts to automate repetitive tasks, such as downloading daily reports.

• View server responses: You can inspect the raw content and headers that a server sends back. Use it if you need to debug network issues or understand how a particular website works.

How cURL Works: The Basics

The basic syntax is:

curl [options] [URL]

1. Fetching a web page

Using cURL with just a URL sends a GET request, displaying the raw HTML source code of that page in your terminal.

curl https://sandbox.oxylabs.io/products/1 

Want to use a cURL GET request to extract public data, like submitting an HTML form, but are unsure about the process? Read our blog on how to send GET requests with cURL.

2. Downloading a file

Using the -O (uppercase O) option saves the file in the current directory under its original name.

curl -O https://sandbox.oxylabs.io/assets/action-adventure.svg 

To dive deeper into cURL download file commands and learn about how to use essential parameters, handle redirects, and manage the process, check how to download files with cURL.

3. Making a POST request

Using the -X POST to specify the method and the -d to include data sends a POST request, submitting that data to the server for processing.

curl -X POST -d "your data" https://httpbin.org/post

For an in-depth guide on sending POST requests with cURL, visit our blog.

We don’t include the PUT request in the basics, because its role – updating existing data – is more advanced than simply fetching or creating. So, let’s explore it in more detail.

What is a PUT Request?

The HTTP PUT method is used to create a new resource or completely replace an existing one at a specific target URL. PUT sends data to a web server with instructions to store it at a client-specified URL. There are two outcomes for this:

• If a resource already exists at that URL, the PUT request will replace the entire existing resource with the content of the request’s payload.

• If no resource exists at that URL, the server may create a new one at that exact location.

So, to put it simply, it’s like saving a file in a specific path. If the file is already there, you overwrite it. If it isn't, you create it.

How Does PUT Differ from POST?

The main difference between PUT and POST lies in the idempotency:

• A PUT request is idempotent – sending it multiple times will have the same effect as sending it once.

• A POST request is not idempotent – sending it multiple times will typically result in creating multiple new resources.

In short, use PUT when you know the precise URL of the resource you want to create or update, and use POST when you want the server to create a new resource and assign its URL.

How to send a PUT request with cURL

The basic syntax uses command-line options like -X PUT to specify the request method and -d to include the data you want to send:

curl -X PUT [options] https://httpbin.org/put 

Sending data with a PUT request

When using cURL to send a PUT request, you can customize its behavior using various command-line options. These include providing authentication headers, sending data from a file, and more.

To update a resource, you must provide new data. For a product API like this, the data is almost always sent in JSON format, which requires specifying a content type header.

• Sending JSON data

To include the data payload, use -d flag. To set the Content-Type header to application/json, use -H flag. With this information, the server will know how to interpret the data you’re sending.

If your product has a name, a price, and stock status, here’s an example of how the JSON data to update would look like:

curl -X PUT -H "Content-Type: application/json" \
-d '{"name": "E-book Reader", "price": 129.99, "in_stock": true}' \
https://httpbin.org/put

• Sending data from a file

If your update data is complex and stored in a file (e.g., update.json), you can send it directly. First, create the update.json file. For example:

echo '{"name": "E-book Reader", "price": 129.99, "in_stock": true}' > update.json

Then, reference this file in your cURL command and send its contents as the requested body:

curl -X PUT -H "Content-Type: application/json" \
-d @update.json \
https://httpbin.org/put

Setting custom headers

Headers are essential for providing metadata, especially for authentication. Content-Type is crucial for PUT requests with a data payload. And since most real-world APIs are protected, you would use Authorization header to provide credentials, for instance, a Bearer token. Here’s an example:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{"status":"active"}' \
  https://httpbin.org/put

If you’re building an API integration and want to configure a proper authorization header for successful authentication, check our step-by-step guide on how to set cURL Authorization header.

Handling the response

To ensure your update was successful, you need to inspect the server’s response. Here’s how to do it:

• Use -i (Include Headers): Displays the HTTP response headers along with the response body, which is the best method for checking the HTTP status code (e.g., 200 OK for success, 404 Not Found if the product doesn't exist).

• Use -v (Verbose): Offers detailed information about the operation, including the headers sent and received.

A successful PUT request typically returns a 200 OK or 204 No Content status code.

curl -X PUT -H "Content-Type: application/json" -d '{"price": 99.99}' -i https://httpbin.org/put 

Common cURL PUT request use cases

To make it clearer, let’s go over a few common examples of when you would use a PUT request:

• Update a user profile by sending new information, such as an email address, name, or phone number, to a specific user ID endpoint.

• Change application settings, for example, update a configuration value for a specific setting key.

• Replace content by altering the entire document or web page content in a CSM at a known URL.

• Upload a file, for instance, to a server at a specific path. It either creates a file at that location or overwrites the existing one.

• Modify product details in an e-commerce system, such as price, description, or inventory count for a specific product ID.

Final thoughts

Using cURL for PUT requests is a powerful way to interact with web servers directly from the command line, especially when updating existing resources or performing automated web tasks. Not only that, but understanding cURL’s command-line options also helps you send accurate PUT requests and makes debugging and automation much easier. If you're new to cURL, check out the what is cURL article on our blog. Additionally, you can learn how to send cURL OPTIONS request for web scraping. And if you need a refresher on how to effectively use cURL for web scraping, head over to our web scraping with cURL tutorial.

However, as useful as cURL is, it can be limited for large-scale operations or web data collection, and you may need additional support for these tasks. That’s where Oxylabs products come in. Suppose you frequently work with proxies for tasks such as scraping, localization testing, or secure API updates. In that case, Oxylabs' Residential Proxies and Datacenter Proxies offer reliable, high-performance solutions that integrate seamlessly with cURL.