---
layout: docs
page_title: Patch data
description: >-
   Make partial updates or add new keys to versioned data in the kv v2 plugin
---

# Patch versioned key/value data

Use the patch process to update specific values or add new key/value pairs to
an existing data path in the `kv` v2 plugin.

<Tip title="Assumptions">

- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). 
- Your authentication token has appropriate permissions for the `kv` v2 plugin:
   - **`patch`** permission to make direct updates with `PATCH` actions.
   - **`create`**+**`update`** permission to make indirect updates by combining
     `GET` and `POST` actions.

</Tip>


<Tabs>

<Tab heading="CLI" group="cli">

Use the [`vault kv patch`](/vault/docs/command/kv/patch) command and set the
`-cas` flag to the expected data version to perform a check-and-set operation
before applying the patch:

```shell-session
$ vault kv patch                 \
   -cas <target_version>         \
   -max-versions <max_versions>  \
   -mount <mount_path>           \
   <secret_path>                 \
   <key_name>=<key_value>
```

For example:

<CodeBlockConfig hideClipboard="true">

```shell-session
$ vault kv patch -cas 2 -mount shared dev/square-api prod=5678

======= Secret Path =======
shared/data/dev/square-api

======= Metadata =======
Key                Value
---                -----
created_time       2024-11-13T21:52:10.326204209Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2
```

</CodeBlockConfig>

If the `-cas` version is older than the current version of data at the target
path, the patch fails:

<CodeBlockConfig hideClipboard="true">

```shell-session
$ vault kv patch -cas 1 -mount shared dev/square-api prod=5678

Error writing data to shared/data/dev/square-api: Error making API request.

URL: PATCH http://192.168.0.1:8200/v1/shared/data/dev/square-api
Code: 400. Errors:

* check-and-set parameter did not match the current version
```

</CodeBlockConfig>

To **force** a patch, you can exclude the `-cas` flag **or** use the
`read+write` patch method with the `-method` flag. For example:

```shell-session
$ vault kv patch -method rw -mount shared dev/square-api prod=5678

======= Secret Path =======
shared/data/dev/square-api

======= Metadata =======
Key                Value
---                -----
created_time       2024-11-13T21:58:32.128442898Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            3
```

Instead of using an HTTP `PATCH` action, the `read+write` method uses a sequence
of `GET` and `POST` operations to fetch the most recent version of data stored
at the targeted path, perform an in-memory update to the targeted keys, then
push the update to the plugin.

</Tab>

<Tab heading="GUI" group="gui">

@include 'gui-page-instructions/select-kv-mount.mdx'

- Click through the path segments to select the relevant secret path.
- Click **Create new version +** on the key/value page.
- Edit the values you want to update.
- Click **Save**.

![Partial screenshot of the Vault GUI showing two editable key/value pairs at the path dev/square-api](/img/gui/kv/patch-data.png)

</Tab>

<Tab heading="API" group="api">

1. Create a JSON file with the key/value data you want to patch. Use the
`options` field to set optional flags and `data` to define the key/value pairs
you want to update.

1. Make a `PATCH` call to
   [`/{plugin_mount_path}/data/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#patch-secret)
   with the JSON data file and the `Content-Type` header set to
   `application/merge-patch+json`:
    ```shell-session
    $ curl                                                  \
      --request PATCH                                       \
      --header "X-Vault-Token: ${VAULT_TOKEN}"              \
      --header "Content-Type: application/merge-patch+json" \
      --data @data.json                                     \
      ${VAULT_ADDR}/v1/<plugin_mount_path>/data/<secret_path>
    ```


For example:

<CodeBlockConfig hideClipboard="true">

```json
{
  "options": {
    "cas": 4
  },
  "data": {
    "smoke": "efgh"
  }
}
```

</CodeBlockConfig>

<CodeBlockConfig hideClipboard="true">

```shell-session
$ curl                                                      \
    --request PATCH                                         \
    --header "X-Vault-Token: ${VAULT_TOKEN}"                \
    --header "Content-Type: application/merge-patch+json"   \
    --data @data.json                                       \
    ${VAULT_ADDR}/v1/shared/data/dev/square-api | jq

{
  "request_id": "6f3bae46-6444-adeb-372a-7f100b4117f9",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2024-11-15T02:52:24.287700164Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 5
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "kv"
}
```

</CodeBlockConfig>

</Tab>

</Tabs>