Curl PUT Example — Replace a Resource with curl

The command

curl -X PUT https://httpbin.org/put \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","role":"admin"}'

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

What the flags do

Flag	What it does
`-X PUT`	Use PUT as the method for a body given with `-d`.
`-T file`	Upload a file with PUT, streaming it rather than loading it into memory.
`-H "If-Match: etag"`	Only replace the resource if it is still the version you read.

Uploading a file with -T

-T (--upload-file) uses PUT on its own and reads the file as a stream, so it works for large files where -d @file would hold everything in memory and strip newlines. If the URL ends in a slash, curl appends the local filename to it. Curl does not guess a media type for -T, so set Content-Type yourself.

curl -T backup.tar.gz \
  -H "Content-Type: application/gzip" \
  https://files.example.com/backups/backup.tar.gz

Replace means replace

A PUT body is the complete new representation. Fields you leave out are not "unchanged"; on a correctly implemented API they are gone or reset to defaults. If you want to change one field, that is PATCH.

Because sending the same PUT twice leaves the server in the same state, it is safe to retry after a timeout. To avoid overwriting somebody else's edit, send the ETag you received as If-Match; the server answers 412 Precondition Failed if the resource changed in between.

curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -H 'If-Match: "33a64df5"' \
  -d '{"name":"Ada","role":"admin","active":true}'

Common mistakes

-X PUT with no data sends an empty PUT, which many APIs read as "set everything to blank".
With -L, -X PUT is reused on every redirect hop, including ones where the server expected a GET.
Expect 201 or 200/204. 201 Created means the URL did not exist before; 200 or 204 means an existing resource was replaced.

Related curl examples

Curl PATCH Request Example

PATCH changes part of a resource.

Curl POST Example

Curl switches to POST the moment you give it a body.

Curl DELETE Request Example

Deleting with curl is one flag.

Curl POST File Example

There are three different things people mean by "post a file", and they are three different requests.

All Curl Examples

49 worked examples, grouped by what you are trying to do.

More under Methods

References

curl man page: -T — Uploading a file, which uses PUT for HTTP URLs.
MDN: PUT — Replacement semantics and idempotency.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ

How do I send a PUT request with curl?

Use -X PUT with a body, for example curl -X PUT -H "Content-Type: application/json" -d '{"name":"Ada"}' URL. To upload a file, use curl -T file URL instead.

What is the difference between curl -X PUT -d and curl -T?

-X PUT -d sends data given on the command line or read into memory from a file. -T streams a file from disk with PUT and is the better choice for large uploads.

Is PUT idempotent?

Yes. Repeating the same PUT leaves the resource in the same state, which makes it safe to retry after a network failure.