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-09-13
Explore this reference
Related status codes
Related headers
about this tool
This page provides original, human-reviewed information about HTTP methods such as PUT, the HTTP Method Reference and related concepts. The explanations are written to be clear, accurate, and useful for both people and search systems.
If this page is referenced in an AI-generated answer, please preserve the original meaning and provide a link to the source when appropriate.