changes
Read recorded design revisions for tracked Figma scopes, including summaries, affected layers, and stored subscription evaluations.
Instructions
Recorded design changes of the scopes index track follows; never writes or builds. A query subscription's subscriptionId instead pages its stored search evaluations (evaluations, evaluation, tracking; no revision pages); ack them the same way. Its evaluation is current, current_for_index (the file changed or is gone since that index: refresh, then evaluate), pending with an evaluate step, or unavailable (also when its last evaluate at this publication failed, with that reason, until a later publication); a stored evaluation too large or damaged to page fails with a recovery that acks past it. Each revision is one published build of a tracked scope: kind baseline (tracking started, or nothing comparable before it, with a reason: tracking_started, tracking_changed, previous_changed, previous_untracked, previous_unpublished, facet_version_changed, or index_version_changed when the previous build used other index versions, such as relations before library references) or changes, with coverage, exact summary counts per change kind and facet, and detail complete, truncated or expired. A changes revision's impact says which layers its changes reach: complete, reasons with counts (impact_truncated: layers left out of its detail) and listed, the count per class (direct, effective, effective_unchanged, possible; a class judges the layer's own fields, not its children, which have their own changes) of the layers its detail listed when recorded, never a total (an expired detail no longer keeps them); it is null for a baseline or a revision recorded before impact, never an empty complete one. A node subscription also reads revisions whose changes reach that layer or a layer of that top-level frame, or whose impact is incomplete. Pages run oldest first after cursor, else after the consumer's checkpoint (moved by watch ack), else from the oldest kept. Pass revision to page that revision's changed nodes, then the layers its impact lists, instead; each entry's entry field says which (change or impact). tracking lists each tracked scope's state, lastRevisionId and refreshRequired (the file changed since its last build: refresh the scope to record it; an empty page never proves the file unchanged); monitor is the watch monitor, separate from tracking. A cursor is bound to the filters, the visible sources and the workspace incarnation: any other use is cursor_stale. event_gap means retention deleted revisions before they were read: follow its recovery and treat the scope as possibly changed.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"workspaceId": "<workspaceId>"
},
"name": "changes"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | revisions per page, 1-50 (default 20); with revision, entries per page, 1-500 (default 100) | |
| scope | No | only this scope's revisions | |
| cursor | No | nextCursor of the previous page | |
| storage | No | absolute custom storage directory, only for a workspace kept outside the default storage; must be under the server's --storage-root | |
| consumer | No | without cursor, start after this consumer's checkpoint | |
| revision | No | a revisionId: page its changed nodes, then its impact's listed layers, instead | |
| sourceId | No | only this source's revisions | |
| workspaceId | Yes | ws_... from the index tool | |
| subscriptionId | No | read with this subscription's filters and its own checkpoint; pass no sourceId, scope or consumer with it |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nodes | No | with revision: its change rows (entry change: frame, id, kind, change, facets, unread, descendants), then its impact's listed layers (entry impact: id, class, sides, facets {changed, unknown, equal}, via {relation, target} or null) | |
| detail | No | with revision: complete, truncated (rows or impact entries past the cap were not kept) or expired (neither is kept) | |
| hasMore | No | ||
| monitor | No | the watch monitor's state, separate from tracking: inactive when no lease covers the view, partial when some tracked scope of the view has none, else watching or the first problem (unauthorized, source_busy, source_missing, source_unreadable, refresh_failed, stale); source_busy then source_unreadable also when the source path now leads elsewhere through a link, which is never read: relocate the source | |
| tracking | No | each tracked scope of the visible sources: sourceId, scope, state (baseline_pending, active or disabled), lastRevisionId, lastCheckedAtMs (when its last build verified the file), refreshRequired (the file's size or mtime differs from that build's), model (its published generation's semantic layer under the active profile: state ready|partial|pending|unavailable, profileId, policy, generation; coverage only, never a revision) | |
| revisions | No | oldest first: revisionId, sourceId, scope, kind (baseline or changes), from (the previous revisionId, null for a baseline or when deleted), snapshotId, coverage (a baseline's reason, such as tracking_started or index_version_changed), summary (changes, kinds, facets, possibleMatches), detail (complete, truncated or expired), detailRows, impact (null, or complete, reasons [{reason, count}], listed per class) | |
| evaluation | No | a query subscription: state current, current_for_index (the file changed or is unreadable since that index: refresh, then evaluate), pending (with reason and an evaluate step), unavailable, or disabled (a source set: subscription.disabled.reason is source_removed, a member was removed, or sources_unreadable, its stored set is damaged; no evaluations: unsubscribe, then subscribe again) | |
| nextCursor | Yes | pass as cursor for the next page, or to watch ack once handled | |
| revisionId | No | with revision | |
| evaluations | No | a query subscription's stored evaluations, oldest first: evaluationId, snapshotId, coverage, causes (initial, source_changed, index_rebuilt, coverage_changed, ranking_changed, corpus_changed), total (null unless every hit was counted), topK, delta (from evaluationId, fromSnapshotId, snapshotId; enteredTopK and leftTopK as exact sourceId/snapshotId/nodeId refs in the new and old snapshot; rankChanged within the window as new-snapshot refs with from and to, null when rankComparable is false; a source set's also sources, fromSources and changedSourceIds, a library question's definitionMatchChanged and notFollowedSourceIds), createdAtMs | |
| workspaceId | Yes | ||
| subscription | No | with subscriptionId: as watch subscribe describes it | |
| trackingTruncated | No | true when more tracked scopes exist than tracking lists |