api.history.commits()

The Time Machine, read-only: the commits of the current map — or of a campaign, map or character you name — newest first.

Part of the Action API · Function reference · Since Action API 0.3 (v0.100.0)

Signature

api.history.commits(
  ref?: { type: 'campaign' | 'map' | 'character'; id: string },
  options?: { limit?: number },
): Promise<HistoryCommit[]>

Asynchronous — await it.

Parameters

Parameter	Type	Description
`ref`	`{ type, id }`	Which entity's history. Optional: the map the action is running on. A token has no history of its own — its changes are commits of its map.
`options.limit`	`number`	How many commits, 1–200. Optional; 50.

Returns

The commits, newest first. Each is:

Field	Type	Meaning
`id`	`string`	The commit.
`parentId`	`string \| null`	The commit before it on its timeline; `null` for the first.
`diffSummary`	`string \| null`	One line: `"2 tokens moved"`, `"name, 1 drawing added"`, `"created"`, `"deleted"`.
`reason`	`string`	What wrote it: `"token updated"`, `"drawing removed"`, `"restored to c_…"`.
`authorName`	`string \| null`	Who — a username, never an email. `null` for the platform.
`at`	`string`	When, ISO 8601.
`restoreOf`	`string \| null`	When the commit is a restore, the commit it restored.
`entityType`, `entityId`		What it is a commit of.

Empty when the entity has no commits yet.

Example

const [latest, previous] = await api.history.commits();
if (!latest) return sendMessage('Nothing has changed on this map yet.');
sendMessage(`<b>Last change:</b> ${latest.diffSummary} — ${latest.authorName ?? 'the platform'}`);

Needs a map, and the user's own access

This only works from an action run on an open map (the impersonated-token bar or the map's menu); anywhere else it throws api.history needs an open map. The read is the user's: an entity they may not read answers 403, which surfaces as a thrown error with the server's sentence.

Read-only by design: an action can show what changed; putting it back is the user's edit, with their name on it. See api.history.diff().