Read a surface as it was at a version
Replays the workspace event log to reconstruct the surface's title and block tree at the given version. Requires `blocks:read` on the surface, since a historical version exposes the same content as the live one. The version must be a positive integer inside the plan's history window, and `approximate` comes back true when the replay hit its event cap and the reconstruction may be incomplete.
Authorization
apiKey Workspace API key created in Workspace settings → API keys. Scopes on the key bound what it can read and write.
In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/workspaces/string/surfaces/string/history/string"{ "data": { "surfaceId": "string", "version": 0, "title": "string", "blocks": [ { "id": "string", "workspaceId": "string", "surfaceId": "string", "parentBlockId": "string", "kind": "paragraph", "orderKey": "string", "manifest": {}, "layout": { "x": 0, "y": 0, "w": 0, "h": 0, "tab": "string" }, "plainText": "string", "createdAt": "string", "updatedAt": "string" } ], "approximate": true }}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}List a surface's revisions
Returns the surface's edit history as revisions: bursts of consecutive events by the same actor collapsed into one entry with its version range, actor, timestamp, and event count. Requires `blocks:read` on the surface, the same gate as reading its current blocks, and the workspace plan's history window bounds how far back revisions go. Paginated: pass `limit` and the `cursor` from the previous response to fetch older revisions; a non-integer `limit` or a cursor that is not a positive integer is a validation error.
Restore a surface to an earlier version
Rewrites the surface's blocks back to the state reconstructed at the given version in one transaction, emitting ordinary block delete and create events so the restore is itself a revision and can be undone by restoring forward. Requires `surfaces:write` on the surface. A version outside the plan's history window, or one whose replay is only approximate, is refused.