Browse docs+

Update Vault Item

Updates vault-item metadata and applies field-level add, update, or delete operations.

PATCH /api/v1/machine/vault-item/:id/update

Important

This is the machine API write path for editing vault-item fields. There is no separate per-field edit endpoint.
This write path no longer requires detailCheckpoint or summaryCheckpoint fields in the request body.
Field changes are sent in the updates array with action: "add", action: "update", or action: "delete".
Item names, field labels, notes, and websites are metadata, so they are not end-to-end encrypted.
Field value payloads should already be client-encrypted v3 vault envelopes when they contain secrets.

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your machine API key
`Content-Type`	string	Yes	Must be `application/json`

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the vault item to update

Request Body

Field	Type	Required	Description
`name`	string	No	Optional new vault-item name
`notes`	string \| null	No	Optional notes metadata
`type`	string	No	Optional new vault-item type
`websites`	string[]	No	Optional replacement website list
`updates`	array	Yes	Field mutations to apply to the vault item

Update Entry Object

Field	Type	Required	Description
`action`	string	Yes	One of `add`, `update`, or `delete`
`fieldId`	string	No	Required for `update` and `delete`; optional client-chosen ID for `add`
`fieldInstanceId`	string	No	Required for `add` and `update`
`assetId`	string	No	Optional asset attachment for the field instance
`name`	string	No	Field label; required for `add`, optional for `update`
`value`	string	No	Latest stored value for the field instance
`type`	string	No	Field type; required for `add`, optional for `update`
`order`	number	No	Optional display-order override
`isEnvironmentVariable`	boolean \| null	No	Marks the field for environment-variable export tooling

Response

Success (200 OK)

Returns the full updated vault-item detail payload, including the latest active field instances, refreshed activity metadata, and effective access.

Notes

action: "add" creates a new field and field instance.
action: "update" archives the previous active field instance and creates a new one.
action: "delete" archives the field and its active instances.
This endpoint requires machine.vault.write plus WRITE access to the target vault item.

Example Request

curl -X PATCH "https://r4.dev/api/v1/machine/vault-item/507f1f77bcf86cd799439021/update" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Database",
    "websites": ["https://db.example.com"],
    "updates": [
      {
        "action": "add",
        "fieldId": "507f1f77bcf86cd799439041",
        "fieldInstanceId": "507f1f77bcf86cd799439062",
        "name": "Password",
        "type": "PASSWORD",
        "value": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}",
        "isEnvironmentVariable": true
      }
    ]
  }'