Reviewing and Undoing an Agent's Changes

In the Editor

If you have the document open when a changeset lands, you see it happen. The change arrives on your canvas straight away, everything it touched is outlined in its author's colour for two seconds, and a note appears at the bottom of the screen:

The note reads name changed n elements, followed by the summary the agent gave the change, when it gave one: "Webber changed 2 elements: add payment service". The name is the person whose token made the change, so an agent working for you shows your own name. Elements added and removed count as changed.

• Show brings the changed elements into view, switching to their tab if you are on another one.
• Undo reverts the change. Afterwards the note reads Undone, or, when some elements were changed again in the meantime, something like Undone, 2 kept because they changed since (see What Undo Keeps).
• If the undo fails, the note offers Show and Undo again, and an error says "Could not undo Webber's change".

The note stays until you close it. Changes from the same token within ten seconds of each other share one note, with the counts added up and the latest summary, and Undo on it reverts each of them, newest first. A newer burst from the same token replaces the note.

Your own Undo shortcut (Ctrl+Z or ⌘Z) never takes back an agent's change: it only ever undoes your own edits. Anything you change while the agent works is kept, and an element you have selected is off limits to it: the changeset is refused and the agent is told who holds it.

The note is an information message, so switching off In-Editor Notifications in Settings hides it; the outline still shows. Undo needs edit access to the tab, so Viewers and Participants see changes arrive but can't revert them.

Once the Note Is Gone

The editor has no history of changesets. Once you close the note, or if the change landed while you didn't have the document open (it simply appears when you next open it, with no outline and no note), review and undo it from the CLI or the API, below.

From the API

Three routes read and revert changesets, with the same authentication as the rest of the API:

Each changeset in the list looks like this:

{
  "id": "cs_8k2m4q7d1x",
  "tabId": "tab-1",
  "rev": 42,
  "author": { "name": "Webber", "color": "#8b5cf6" },
  "agent": true,
  "summary": "add payment service",
  "counts": { "added": 2, "changed": 0, "removed": 0 },
  "revertOf": null,
  "createdAt": 1791710040000
}

agent is true when an API token made the change. Only the person who made it also sees the tokenId of the token that did. The single-changeset route answers { "changeset": { … }, "results": [ … ], "text": "…" }, where text is the lines changeset show prints under the summary line. A revert answers:

{
  "changeset": {
    "id": "cs_5m2q8r1t6w",
    "tabId": "tab-1",
    "rev": 45,
    "previousRev": 44,
    "rebasedOver": 0
  },
  "reverted": 1,
  "kept": [{ "id": "pay", "reason": "changed" }]
}

It also carries lint, the lint report of the tab the revert leaves. changeset is null when there was nothing to revert.

Reading the history needs read access to the document; reverting needs edit access to the tab. A revert made with a token is refused with 409 elements_held when somebody has one of its elements selected, as any agent change is; one made from the editor's Undo never is. See Errors and Rate Limits for the other answers.

How Long You Can Undo

A changeset can be reviewed and reverted for 30 days after it lands, the same as the Trash keeps a deleted document. After that its record is deleted: it no longer appears in the list, and showing or reverting it answers 404. The change itself stays on the tab.