Replaces the target resource with the request payload, or creates it if it does not exist. Idempotent.
Quick facts
| Property | Value |
|---|---|
| Safe (does not modify state) | No |
| Idempotent (repeatable) | Yes |
| Cacheable | No |
Description
Replaces the target resource with the request payload, or creates it if it does not exist. Idempotent.
Example
curl -X PUT https://api.example.com/users/1 -H "Content-Type: application/json" -d '{"name":"Ada"}'Request example
PUT /api/users/1 HTTP/1.1
Host: example.com
Content-Type: application/json
{"name":"Ada"}PUT vs PATCH
| PUT | PATCH |
|---|---|
| Replace the whole resource | Apply a partial update |
| Idempotent | Not necessarily |
| Full body required | Smaller payload |
All HTTP methods
Frequently asked questions
PUT is not a safe method — calling it can change resource state.
PUT is idempotent — repeated requests have the same effect as a single request.
Sources & standards
Updated 2026-08-18
Explore this reference
Related status codes
Related headers