---
{
  "id": "platform.note.editing-and-versioning",
  "topic": "note",
  "title": "Note editing, conflicts, and roll-forward versions",
  "locale": "en",
  "version": "2026-08-25",
  "summary": "Note updates preserve omitted fields, replace tags as a set, reject blank content, and use optimistic locking and immutable roll-forward version history.",
  "content": "`update_note` is a partial update: omitted fields retain their current values, while a supplied `tags` array replaces the complete tag set rather than merging it. Explicit empty or whitespace-only `content` is rejected with detail code `NOTE_CONTENT_EMPTY`; clearing the body is not a legal action operation. Omit `content` to preserve it. For concurrent work, first call `get_note`, pass its version as `expectedVersion`, and treat `RESOURCE_CONFLICT` with expected and actual versions as a signal to reread, deliberately merge, and retry. Never blindly resend a stale write.\n\nEvery successful create, update, or restore writes a full version snapshot and advances the note version monotonically. `list_versions` and `get_version` are owner-scoped reads; list results mark the current snapshot with `isCurrent`. `restore_version` is roll-forward: it copies the selected old snapshot into a new current version without deleting or rewriting history. The content current immediately before restore already has its own snapshot, so it can be restored again later.\n\n`create_named_version` records the current title, content, and tags as a durable checkpoint with an optional label. It needs no confirmation, is private, uses Strict drift, and should be called only when the user explicitly asks for a named checkpoint.\n\nRestore resets stored CRDT state and synchronizes active editors; the live result determines whether that synchronization succeeded. Registry confirmation for `restore_version` is `none`, but restore overwrites current content. Before executing it, use `get_version`, summarize the selected snapshot to the user, and obtain clear intent; do not claim that the platform will add a separate confirmation prompt. `create_note` and `update_note` each cap total serialized arguments at 32 KiB, and content replacement is whole-body. A note too large for that bound cannot be rewritten in full through these actions; do not invent append or patch behavior.\n",
  "aliases": [
    "edit note",
    "update personal note",
    "note version history",
    "expectedVersion",
    "NOTE_CONTENT_EMPTY",
    "restore note version",
    "note conflict"
  ],
  "tags": [
    "note",
    "editing",
    "versions",
    "optimistic-locking",
    "collaboration"
  ],
  "relatedActions": [
    "arinova.note.get_note",
    "arinova.note.create_note",
    "arinova.note.update_note",
    "arinova.note.list_versions",
    "arinova.note.get_version",
    "arinova.note.create_named_version",
    "arinova.note.restore_version"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/note/editing-and-versioning/"
}
---

`update_note` is a partial update: omitted fields retain their current values, while a supplied `tags` array replaces the complete tag set rather than merging it. Explicit empty or whitespace-only `content` is rejected with detail code `NOTE_CONTENT_EMPTY`; clearing the body is not a legal action operation. Omit `content` to preserve it. For concurrent work, first call `get_note`, pass its version as `expectedVersion`, and treat `RESOURCE_CONFLICT` with expected and actual versions as a signal to reread, deliberately merge, and retry. Never blindly resend a stale write.

Every successful create, update, or restore writes a full version snapshot and advances the note version monotonically. `list_versions` and `get_version` are owner-scoped reads; list results mark the current snapshot with `isCurrent`. `restore_version` is roll-forward: it copies the selected old snapshot into a new current version without deleting or rewriting history. The content current immediately before restore already has its own snapshot, so it can be restored again later.

`create_named_version` records the current title, content, and tags as a durable checkpoint with an optional label. It needs no confirmation, is private, uses Strict drift, and should be called only when the user explicitly asks for a named checkpoint.

Restore resets stored CRDT state and synchronizes active editors; the live result determines whether that synchronization succeeded. Registry confirmation for `restore_version` is `none`, but restore overwrites current content. Before executing it, use `get_version`, summarize the selected snapshot to the user, and obtain clear intent; do not claim that the platform will add a separate confirmation prompt. `create_note` and `update_note` each cap total serialized arguments at 32 KiB, and content replacement is whole-body. A note too large for that bound cannot be rewritten in full through these actions; do not invent append or patch behavior.