Skip to main content
GET
Read Changes
Returns the next page of the workspace change feed (artifact, folder, task, and workspace events, in commit order) after this API key’s acknowledged position. This is where an agent catches up: Load shows the latest changes and how many are unread, and this feed reads those unread changes in order, and among the agent reads is the only one that reports history gaps (historyGap) and access changes (refresh); load reports neither. Reading never acknowledges: call Acknowledge with the page’s deliveryToken to move forward. A workspace in the trash answers 410 WORKSPACE_DELETED. MCP: workspace_changes. CLI: rip workspace changes <workspace> [--limit --delivery-token]. Auth: Authorization: Bearer tr_... (an account API key). {id} is the workspace id or slug (any case; a slug two of your workspaces share is 409 AMBIGUOUS_REFERENCE listing each candidate’s id).

Query parameters

Response

Only one page is outstanding at a time. While it is, a read without its deliveryToken is refused; a read with it returns the same page. Each page answers from one consistent snapshot and does not wait for agents writing into the workspace; two reads by the same key at once answer as they would one after the other. Once the token expires, the next read issues a fresh page from your acknowledged position. Your first read opens a catch-up window that ends at the workspace’s latest change at that moment; the window holds until you have acknowledged through it, so changes made meanwhile come in the next window. An access change or a history gap resets the window, and your next read opens a new one. Load never opens or moves it. History sequence numbers are positions in that window, not visible-event counts or content revisions, so a page can be older than the current content load shows. Consume, replay, and explicitly acknowledge the delivered page to reach the next window. Acknowledgment consumes history; it cannot resolve a content-write conflict. Browser rendering and polling never acknowledge visible work.

Errors