Replace a resource with PUT

Overview

Use PUT to replace a resource wholesale with a new representation. The body you send becomes the resource's complete new state.

In code

curl -X PUT https://api.example.com/users/1 \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","role":"admin"}'

await fetch('https://api.example.com/users/1', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Ada Lovelace',
    email: 'ada@example.com',
    role: 'admin'
  })
});

import requests

res = requests.put('https://api.example.com/users/1',
                   json={'name': 'Ada Lovelace',
                         'email': 'ada@example.com',
                         'role': 'admin'})
res.raise_for_status()

Details

PUT is a full replacement, not a merge. Fields you omit may be dropped or reset to defaults depending on the server, so send the entire representation. Use PATCH if you only want to change part of it.

PUT is idempotent: calling it repeatedly with the same body leaves the same final state, so it is safe to retry after a network error.

Response codes vary. Updating an existing resource yields 200 (with body) or 204 (no body); creating one at the target URL may return 201. To guard against concurrent edits, add `If-Match: "<etag>"` for optimistic locking, which makes the server return 409 on a stale write.

Related headers

Related status codes