Curl PATCH Request Example

The command

curl -X PATCH https://httpbin.org/patch \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

Run this request in the API Tester

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

What the flags do

Two patch formats, two media types

Most JSON APIs accept a partial object and merge it: fields present are updated, fields absent are left alone. That is JSON Merge Patch (application/merge-patch+json), although many servers accept it under plain application/json. Its one sharp edge: null means "delete this field", so you cannot use it to set a value to null, and arrays are replaced whole.

JSON Patch (application/json-patch+json) is a list of operations instead. It can append to an array, move a value, or test a value before changing it, at the cost of being more verbose.

# JSON Merge Patch: change role, remove nickname
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"role":"admin","nickname":null}'

# JSON Patch: a list of operations
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json-patch+json" \
  -d '[{"op":"replace","path":"/role","value":"admin"},
       {"op":"add","path":"/tags/-","value":"beta"}]'

PATCH is not automatically safe to retry

Unlike PUT, a PATCH is not guaranteed to be idempotent. Setting role to admin twice is harmless, but an operation such as "append to this list" or "increment this counter" is applied again on a retry. If a request times out and you cannot tell whether it landed, read the resource before sending it again, or use If-Match with the ETag you last saw.

Common mistakes

• Sending a JSON Patch array as application/json usually gets a 400 or 415: the server tries to merge an array into an object.
• 405 Method Not Allowed means the endpoint does not implement PATCH at all. Check the Allow response header for what it does accept.
• Shell quoting. Wrap the JSON in single quotes on Linux and macOS; on Windows read the body from a file with -d @patch.json.

Related curl examples

More under Methods

• Curl GET Request Example
• Curl POST Example
• Curl HEAD Request Example
• Curl OPTIONS Request Example

References

• curl man page: -X — Setting a custom request method.
• MDN: PATCH — Partial updates and why PATCH is not necessarily idempotent.
• RFC 7396: JSON Merge Patch — The merge format most JSON APIs accept.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ