Updated September 2026.
01Introduction
The difference between PUT and PATCH is scope. PUT replaces the entire resource with the body you send, and PATCH changes only the fields you include.
That one difference decides what happens to fields you leave out, whether a request is safe to retry, and which errors your clients will see. This guide walks through each with request examples you can copy, then gives you a short rule for choosing.
If you are new to APIs, start with our beginner's guide to APIs and come back. Everything below assumes you know what a request body is. If that term is new, this explainer on payloads covers it in five minutes.
02PUT vs PATCH at a glance
| PUT | PATCH | |
|---|---|---|
| What it does | Replaces the whole resource | Changes part of the resource |
| What you send | The complete resource | Only the fields to change |
| Missing fields | Reset, removed or rejected | Left as they are |
| Idempotent | Yes, by definition | Not by default |
| Can create a resource | Yes, at a URL the client chooses | Rarely |
| Safe to retry automatically | Yes | Only if you design it to be |
| Defined in | RFC 9110 | RFC 5789 |
All the examples below use this user resource:
{
"id": 123,
"name": "Alice",
"plan": "starter",
"timezone": "Europe/Amsterdam"
}03What is PUT in a REST API?
PUT sends a complete replacement for the resource at a URL. The server stores what you send as the new version, in full.
To move Alice to the pro plan with PUT, you send every field, including the ones that did not change:
PUT /users/123 HTTP/1.1
Content-Type: application/json
{
"name": "Alice",
"plan": "pro",
"timezone": "Europe/Amsterdam"
}{
"id": 123,
"name": "Alice",
"plan": "pro",
"timezone": "Europe/Amsterdam"
}Leave timezone out and the server has three options: reset it to a default, remove it, or reject the request with 400 or 422. All three are valid PUT behavior. Your API documentation should say which one yours does, because clients cannot guess.
PUT is idempotent. Sending the same PUT once or ten times leaves the resource in the same state, which is why clients and proxies can retry it after a timeout.
04What is PATCH in a REST API?
PATCH sends a set of changes. The server applies them to the current version and leaves every other field untouched.
The same plan change with PATCH:
PATCH /users/123 HTTP/1.1
Content-Type: application/merge-patch+json
{
"plan": "pro"
}{
"id": 123,
"name": "Alice",
"plan": "pro",
"timezone": "Europe/Amsterdam"
}The request body is one field instead of three. On a resource with 40 fields, that difference is the reason PATCH exists.
The catch is idempotency. RFC 5789 states that PATCH is neither safe nor idempotent by default, although a PATCH request can be written so that it is. The next two sections show where that matters.
05JSON Merge Patch vs JSON Patch
"PATCH" does not tell the server how to read your body. The Content-Type does. Two formats cover almost every JSON API.
JSON Merge Patch (RFC 7396)
Content type: application/merge-patch+json. You send a partial copy of the resource. Fields you include are added or replaced. Fields set to null are removed. Everything else stays.
To remove Alice's timezone:
PATCH /users/123 HTTP/1.1
Content-Type: application/merge-patch+json
{
"timezone": null
}Merge Patch is readable and covers most everyday updates. It has two limits, both from RFC 7396: you cannot set a field to a literal null, because null means "remove", and arrays are replaced whole, so you cannot add one item to a list.
JSON Patch (RFC 6902)
Content type: application/json-patch+json. You send a list of operations: add, remove, replace, move, copy and test.
PATCH /users/123 HTTP/1.1
Content-Type: application/json-patch+json
[
{ "op": "test", "path": "/plan", "value": "starter" },
{ "op": "replace", "path": "/plan", "value": "pro" }
]The test operation makes the whole patch fail if plan is no longer starter. That turns a blind update into a conditional one, and it makes this request safe to retry: the second attempt fails the test instead of changing anything.
JSON Patch can also edit arrays precisely. That is also where PATCH stops being idempotent:
[
{ "op": "add", "path": "/tags/-", "value": "beta" }
]Send that twice and Alice ends up with two beta tags. See the full format in RFC 6902.
06PUT vs POST vs PATCH
POST is the third method people mix up with these two.
| POST | PUT | PATCH | |
|---|---|---|---|
| Typical use | Create a resource, or trigger an action | Create or fully replace at a known URL | Partially update an existing resource |
| Who picks the URL | The server | The client | The client |
| Idempotent | No | Yes | Not by default |
| Example | POST /users | PUT /users/123 | PATCH /users/123 |
A useful shortcut: POST to a collection, PUT and PATCH to a single item.
07Status codes for PUT and PATCH
| Code | When you will see it |
|---|---|
| 200 OK | Update applied, updated resource in the body |
| 201 Created | PUT created a resource that did not exist |
| 204 No Content | Update applied, no body returned |
| 400 Bad Request | Body is malformed |
| 409 Conflict | The change conflicts with the resource's current state |
| 412 Precondition Failed | An If-Match check failed because someone else changed the resource first |
| 415 Unsupported Media Type | The server does not accept that patch format |
| 422 Unprocessable Content | Body is valid, but the change cannot be applied |
Servers can advertise which patch formats they accept with the Accept-Patch response header. If a PATCH comes back 415, check that header first.
08Avoiding lost updates
Two clients read Alice's profile. One changes her plan, the other her timezone. With PUT, whoever writes second overwrites the first change without knowing it existed.
The fix works for both methods: send the version you read with If-Match.
http
PATCH /users/123 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "v7"
{
"plan": "pro"
}
If the resource has changed since version v7, the server answers 412 and nothing is written. The client re-reads and tries again.
09When to use PUT vs PATCH
Use PUT when:
- The client holds the complete resource, like a settings form that submits every field.
- You want safe automatic retries with no extra design work.
- The client should be able to create a resource at a URL it chooses.
Use PATCH when:
- You change one or two fields on a large resource.
- Different clients own different fields and should not overwrite each other.
- Payload size matters, for example on mobile connections.
If you support PATCH, pick one format, document it, and return 415 for anything else.
10Why this matters more with AI agents
Agents retry. When a call times out, an agent will often send it again. A PUT survives that. A PATCH that appends to a list or increments a counter does not, and the agent has no way to know the first attempt succeeded.
If agents will call your API, make PATCH requests conditional with If-Match or a JSON Patch test operation, and state each endpoint's retry behavior in the documentation. Knowing how to read API documentation is half of this. Writing docs an agent can act on is the other half.
This is also how ApyHub MCP is built: every endpoint in the catalog is exposed to agents with its full input schema, so an agent can discover, evaluate and call an API directly without a hand-written wrapper or tool definition. For more on connecting agents to APIs, see how to build with AI and APIs.
11Try it on real APIs
The fastest way to make this stick is to send real requests and read real responses. The ApyHub catalog has 450+ services, with new APIs added continuously, and every one has a playground where you can change the body, send the request and see the status code and response. The free tier needs no card.
Create your free ApyHub account →
12Conclusion
PUT replaces, PATCH modifies. PUT is idempotent and easy to retry, but it overwrites anything the client leaves out. PATCH sends less and protects fields the client never touched, but it is only safe to retry if you design it that way.
For most APIs, the practical setup is PUT for full replacements, PATCH with JSON Merge Patch for everyday partial updates, JSON Patch where you need array edits or test conditions, and If-Match on both when more than one client writes to the same resource.
13FAQ
What is the difference between PUT and PATCH? PUT replaces the entire resource with the body you send. PATCH applies only the changes you send and leaves other fields as they are.
Is PATCH idempotent? Not by default. RFC 5789 defines PATCH as neither safe nor idempotent. A PATCH that sets a field to a fixed value behaves idempotently, while one that appends to an array or increments a number does not.
Is PUT idempotent? Yes. RFC 9110 defines PUT as idempotent: repeating the same request leaves the resource in the same state as sending it once.
What happens to fields I leave out of a PUT request? The server resets them, removes them, or rejects the request with 400 or 422. Which one depends on the API, so check its documentation.
What is the difference between PUT, POST and PATCH? POST creates a resource at a URL the server picks, or triggers an action. PUT creates or fully replaces a resource at a URL the client picks. PATCH partially updates an existing resource.
Can PUT create a new resource? Yes. If nothing exists at the URL, a PUT can create it and the server returns 201 Created.
How do I remove a field with PATCH? With JSON Merge Patch, set the field to null. With JSON Patch, use a remove operation on the field's path.
Should I use JSON Merge Patch or JSON Patch? Use JSON Merge Patch for simple field updates, since it is easier to read and write. Use JSON Patch when you need to edit arrays, or when you want a test operation that makes the update conditional.
Which HTTP status code should a successful PATCH return? 200 OK if you return the updated resource, or 204 No Content if you return nothing.
Where can I practice PUT, PATCH and other API requests? Pick any API in the ApyHub catalog and use its playground to edit the request body and inspect the response. The free tier needs no card.
14About ApyHub
ApyHub is a curated API catalog and trusted operational layer. It gives developers and AI agents access to 450+ services and 1,500+ endpoints through a single subscription, with new APIs and providers onboarded continuously. Usage is billed in atoms, a unit that reflects the actual work of each call and is pooled across the entire catalog.
Every endpoint ships with machine-readable certification covering data residency, retention, sub-processors and alignment with GDPR, SOC 2 and ISO 27001, and is MCP-ready by default so agents can discover and call it without custom glue code.
ApyHub is headquartered in Amsterdam, with offices in the Netherlands, Greece and India. More than 65,000 developer workspaces use the catalog every month. There is a free tier and no card is required to start.
If you build APIs, you can publish yours to the catalog at apyhub.com/become-a-provider.