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.
Field changes are sent in the updates array with action: "add", action: "update", or action: "delete".
Item names, field labels, and websites are metadata, so they are not end-to-end encrypted. Only field value payloads are end-to-end encrypted.
detailCheckpoint is always required.
summaryCheckpoint is required only when you change vault-summary-visible item metadata: name, type, or websites.

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
`detailCheckpoint`	object	Yes	Signed replacement detail checkpoint for the updated item
`summaryCheckpoint`	object	No	Signed replacement parent-vault summary checkpoint when item `name`, `type`, or `websites` change
`name`	string	No	Optional new vault-item name. This metadata is not end-to-end encrypted.
`type`	string	No	Optional new vault-item type
`websites`	string[]	No	Optional replacement website list. This metadata is not end-to-end encrypted.
`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 `add`, `update`, and `delete`
`fieldInstanceId`	string	No	Required for `add` and `update`
`name`	string	No	Field label; required for `add`, optional for `update`. This metadata is not end-to-end encrypted.
`type`	string	No	Field type; required for `add` and `update`
`value`	string	No	Latest stored value for the field instance. For encrypted vaults this should already be a client-encrypted v3 envelope
`assetId`	string	No	Optional asset attachment for the new field instance
`order`	number	No	Optional display-order override when updating an existing field

Response

Success (200 OK)

No response body is returned on success.

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 '{
    "detailCheckpoint": {
      "checkpoint": {
        "vaultItemId": "507f1f77bcf86cd799439021",
        "vaultId": "507f1f77bcf86cd799439011",
        "version": 13,
        "name": "Production Database",
        "type": "LOGIN",
        "websites": ["https://db.example.com"],
        "groupId": null,
        "fields": [
          {
            "id": "507f1f77bcf86cd799439031",
            "name": "Username",
            "type": "TEXT",
            "order": 0,
            "fieldInstanceIds": ["507f1f77bcf86cd799439061"],
            "assetIds": []
          },
          {
            "id": "507f1f77bcf86cd799439041",
            "name": "Password",
            "type": "PASSWORD",
            "order": 1,
            "fieldInstanceIds": ["507f1f77bcf86cd799439062"],
            "assetIds": []
          }
        ]
      },
      "signerUserKeyPairId": "507f1f77bcf86cd799439099",
      "signature": "base64-signature"
    },
    "updates": [
      {
        "action": "add",
        "fieldId": "507f1f77bcf86cd799439041",
        "fieldInstanceId": "507f1f77bcf86cd799439062",
        "name": "Password",
        "type": "PASSWORD",
        "value": "{\"v\":3,\"iv\":\"...\",\"t\":\"...\",\"d\":\"...\"}"
      }
    ]
  }'