HTTP PATCH asks a server to apply changes described in a patch document to the resource named by the request URI. Unlike PUT, which sends a representation intended to replace the stored representation, PATCH sends instructions for changing the current one. PATCH is a method, not a particular format: a server must support the patch-document media type you send.
How an HTTP PATCH request works
A PATCH request has a target URI, a request body containing a patch document, and usually a Content-Type header identifying that document’s format. The server interprets the instructions against the target resource. The format and the resource’s rules determine what changes are possible.
There is no universal patch format required by HTTP. A server may accept one format for a resource and reject another, or may not support PATCH for that resource at all. The server is responsible for checking that the patch document is suitable for the target.
A patch can have effects beyond the target resource, and a server may permit PATCH to create a resource that does not yet exist, depending on its implementation and the patch format. Do not assume either behavior: consult the API documentation or discover the resource’s supported methods and formats.
#1 Best Overall
PATCH is not JSON Patch
PATCH is the HTTP method. JSON Patch is one possible document format used with that method, defined by RFC 6902. A JSON Patch body is an ordered sequence of operations on a JSON document and uses the media type application/json-patch+json. Other patch formats exist; an endpoint’s advertised or documented support determines what it accepts.
PATCH vs. PUT
| Question | PATCH | PUT |
|---|---|---|
| What does the request body mean? | Instructions for changing the current resource. | A representation intended to replace the target resource’s stored representation. |
| What format is expected? | A patch-document format supported by that resource, identified by its media type. | The representation being proposed as the replacement; the API defines what representations it accepts. |
| Is the method idempotent? | Not inherently. A particular patch may be designed to be idempotent. | Yes, by HTTP method semantics. |
| When is it a natural fit? | When making a partial change with an accepted patch format. | When replacing the target representation. |
Idempotency means that repeating the same request has the same intended effect as making it once. It does not mean the server cannot record incidental events, such as logging each request. PUT’s idempotency is a method-level property; PATCH’s result depends on the particular instructions and application semantics. See RFC 9110 for HTTP semantics.
Example: sending a PATCH request
The following examples show the shape of a JSON Patch request. api.example.com is an illustrative host, not a real service; replace it with an endpoint whose documentation says it accepts JSON Patch. The operation shown replaces a field named status with active. Whether that path exists and whether the operation is authorized depend on the target API.
cURL
curl -X PATCH "https://api.example.com/users/42"
-H "Content-Type: application/json-patch+json"
-H "Accept: application/json"
--data '[{"op":"replace","path":"/status","value":"active"}]'Python with requests
import requests
url = "https://api.example.com/users/42"
patch = [{"op": "replace", "path": "/status", "value": "active"}]
response = requests.patch(
url,
json=patch,
headers={"Content-Type": "application/json-patch+json"},
timeout=30,
)
response.raise_for_status()
print(response.status_code)
if response.content:
print(response.json())Passing json= serializes the list as JSON; the explicit header is important because JSON Patch has its own media type, which may not be the default application/json used for an ordinary JSON document.
Recommended Free Tools
Node.js
const url = "https://api.example.com/users/42";
const patch = [{ op: "replace", path: "/status", value: "active" }];
const response = await fetch(url, {
method: "PATCH",
headers: {
"Content-Type": "application/json-patch+json",
"Accept": "application/json"
},
body: JSON.stringify(patch)
});
if (!response.ok) {
throw new Error(`PATCH failed: ${response.status} ${await response.text()}`);
}
const result = response.status === 204 ? null : await response.json();
console.log(result);Real APIs may also require authentication, a version header, or other request fields. A successful response may contain a representation or no body, so clients should handle the status and response format the endpoint documents.
Atomicity, concurrency, and retry safety
RFC 5789 requires the server to apply the complete patch atomically: if any part cannot be applied, it must not leave the resource partially changed. This matters for a multi-operation patch: an early operation succeeding does not justify keeping that partial result if a later operation fails.
Atomicity does not by itself prevent another client from changing the resource between your read and your PATCH. If your instructions assume a particular base version, use a conditional request when the server supports it. For example, obtain a strong ETag with the representation and send it in If-Match:
curl -X PATCH "https://api.example.com/users/42"
-H 'Content-Type: application/json-patch+json'
-H 'If-Match: "strong-etag-from-a-prior-response"'
--data '[{"op":"replace","path":"/status","value":"active"}]'If the resource has changed and its current validator no longer matches, the server can reject the conditional operation rather than apply instructions to a version you did not inspect. The exact response and conflict-resolution flow depend on the API.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Do not automatically retry every failed PATCH. A timeout can leave the client unsure whether the server applied the request. A patch that adds an item, increments a value, or otherwise depends on current state may have a different effect if repeated. RFC 9110 advises against automatically retrying a non-idempotent request unless the client knows the request is idempotent or can determine that the original was not applied. Design operations and recovery around the endpoint’s documented semantics; where appropriate, use a conditional request or an application-level idempotency mechanism supported by that API.
Rank #4
Discover accepted methods and patch formats
To inspect a resource’s advertised support, send an OPTIONS request and examine the response:
curl -i -X OPTIONS "https://api.example.com/users/42"Allowlists methods the resource permits, which can include PATCH.Accept-Patchlists patch-document media types the resource accepts. RFC 5789 says it should appear in the OPTIONS response when the resource supports PATCH.- An
Accept-Patchheader in a response to another method also implicitly indicates that PATCH is allowed for that resource.
These headers help with discovery, but the API’s documentation remains important for the meaning of paths, operations, authorization, and validation. Capabilities can vary by resource even within one service.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common PATCH errors and what to check
| Response or symptom | Likely issue | What to check |
|---|---|---|
400 Bad Request |
The patch document may be malformed or invalid for the chosen format. | Validate its syntax, operation names, required fields, and paths against the format and API rules. |
415 Unsupported Media Type |
The server does not accept the request’s patch format for this resource, or the media type is missing or incorrect. | Check the Content-Type and the endpoint’s supported formats. RFC 5789 says a 415 response should include Accept-Patch to identify accepted formats. |
409 Conflict |
The requested change conflicts with current resource state, or the server cannot queue concurrent modifications. | Read the response and API guidance; fetch the latest state and resolve the conflict before constructing another patch. |
| Method rejected or unavailable | PATCH may not be allowed for this URI, even if another resource on the same service supports it. | Check OPTIONS, Allow, and the resource-specific API documentation. |
| Unexpected result after a timeout | The server may have applied the request even though the client did not receive the response. | Do not blindly resend a potentially non-idempotent patch. Check the current resource state or use the API’s documented conditional or idempotency protections. |
These are protocol-level examples, not an exhaustive mapping: the patch format, application, and server determine the appropriate response for a particular failure.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Best Value
Choosing a patch format and approach
- Start with the target resource’s documented or advertised accepted media types; do not assume it accepts JSON Patch.
- Understand the format’s operations and failure rules. JSON Patch defines an ordered operation sequence, and a failed operation means the document has not been successfully applied.
- Decide whether your change is truly partial. If the intended request is a replacement representation, PUT may better express that intent.
- If the patch is based on a version you previously read, consider a conditional request such as
If-Matchwith a strong ETag. - Assess whether repeating the exact operation has the same intended effect before implementing automatic retries.
There is no universally best patch format established by the HTTP specifications. The resource’s capabilities and the application’s semantics determine the suitable choice.
A separate HTTP API example: ScreenshotNeo
ScreenshotNeo is a website screenshot API and MCP server; it is not a PATCH-format provider. Its documented screenshot endpoint is called with a GET request, so it is a separate example of using an HTTP API rather than a way to apply resource patches. Its screenshot API can return PNG, JPEG, WebP, or PDF output. Features include consent-banner and popup removal, CSS-selector captures, custom headers and cookies, and asynchronous jobs. See ScreenshotNeo and its API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpOnly clean shots are billed; bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Does HTTP PATCH create a resource if it does not exist?
It can, depending on the server and patch format; HTTP does not require every PATCH endpoint to create missing resources.
Does a PATCH request have to return the updated resource?
No. The response body and status depend on the server and API; a client should follow the endpoint’s response contract.
Is JSON Patch the only format for PATCH?
No. JSON Patch is one patch-document format. The target resource determines which media types it accepts.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
