PUT

Replacing an entire resource at a known URL requires the HTTP PUT method, which stores the enclosed representation at the target URI.

Table of Contents

Usage

A PUT request tells the server to store the enclosed representation at the specified URI. If the resource already exists, the server replaces its entire state with the new representation. If no resource exists at the URI, the server creates one.

Idempotency

PUT is idempotent. Sending the same PUT request multiple times produces the same server state as sending the request once. This contrasts with POST, where repeated submissions create duplicate resources or trigger processing multiple times.

Idempotency makes PUT safe to retry after network failures. A client unsure whether a previous request arrived sends the request again without risking unintended side effects.

Content negotiation

The server validates the incoming representation against its own constraints. When the Content-Type matches expectations and the content is well-formed, the server stores the resource and responds with 201 Created for new resources or 200 OK / 204 No Content for replacements.

When the media type is incompatible, the server returns 415 Unsupported Media Type. A 409 Conflict response indicates a state conflict unrelated to content type, such as a version mismatch.

PUT vs POST

POST delegates processing to the target resource. PUT specifies the exact URI where the representation belongs. A PUT to /articles/42 stores the article at /articles/42. A POST to /articles asks the collection to create a new article at a server-chosen URI.

PUT vs PATCH

PUT replaces the entire resource. PATCH applies partial modifications. Updating a single field with PUT requires sending the full representation. PATCH sends only the changes.

Properties

Property Value
Safe No
Idempotent Yes
Cacheable No

Example

Creating a resource

A client stores a plain text file at /docs/setup.txt. The server creates the resource and responds with 201 Created.

Request

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

Response

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

Replacing a resource

A client replaces an existing JSON resource at /users/42. The server confirms the update with 200 OK and returns the stored representation.

Request

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

{"name":"Alice","email":"alice@example.re"}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

Conditional update

A conditional request using If-Match prevents overwriting a resource modified by another client. The ETag value ensures the update applies only to the expected version.

Request

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

Response

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

Cross-origin PUT requests always trigger a CORS preflight. The browser sends an OPTIONS request first to confirm the server allows PUT on the target resource.

Response status codes

201 Created indicates the server created a new resource at the target URI. This applies when no resource previously existed at that location.

200 OK confirms an existing resource was replaced and the response includes the updated representation in the body.

204 No Content confirms a replacement with no response body. This is common when the client does not need the stored representation returned.

412 Precondition Failed indicates the If-Match condition was not met. The ETag value provided by the client does not match the current resource version, so the server rejects the update to prevent overwriting changes made by another client.

409 Conflict signals an application-level state conflict unrelated to preconditions, such as a content merge conflict or a version control collision the client needs to resolve manually.

See also

Last updated: April 4, 2026