Read Changes
curl --request GET \
--url https://api.example.com/v0/workspaces/{id}/changesimport requests
url = "https://api.example.com/v0/workspaces/{id}/changes"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v0/workspaces/{id}/changes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/workspaces/{id}/changes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/workspaces/{id}/changes"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v0/workspaces/{id}/changes")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/workspaces/{id}/changes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyWorkspaces
Read Changes
GET /v0/workspaces/:id/changes — A bounded page of workspace changes after your acknowledged position
GET
/
v0
/
workspaces
/
{id}
/
changes
Read Changes
curl --request GET \
--url https://api.example.com/v0/workspaces/{id}/changesimport requests
url = "https://api.example.com/v0/workspaces/{id}/changes"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v0/workspaces/{id}/changes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/workspaces/{id}/changes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/workspaces/{id}/changes"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v0/workspaces/{id}/changes")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/workspaces/{id}/changes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyReturns 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 (
Only one page is outstanding at a time. While it is, a read without its
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
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1–100, default 50 |
deliveryToken | string | Replay the outstanding page instead of asking for a new one |
Response
{
"ok": true,
"data": {
"items": [
{ "id": "…", "type": "artifact.edited",
"actor": { "type": "account", "id": "rip1…", "surface": "claude-code", "alias": "simon" },
"subject": { "type": "artifact", "id": "a1b2…", "title": "Pricing" },
"payload": { "versionId": "9f0a…" },
"why": "Set launch prices the team can defend to finance",
"agent": { "name": "Claude Code (laptop)" },
"agentId": "9b1d0e2a-6c3f-4f1e-8d2a-1f0e5c7b9a31",
"mine": true,
"createdAt": "2026-09-15T09:00:00.000Z" },
{ "id": "…", "type": "artifact.rows_changed",
"actor": { "type": "account", "id": "rip1…", "surface": "codex", "alias": "alice" },
"subject": { "type": "artifact", "id": "e5f6…", "title": "Price list" },
"payload": { "added": 12, "updated": 3, "deleted": 0 },
"why": "Add the enterprise tiers",
"agent": null,
"agentId": "4c2e8f11-0b7d-4a6e-9f3c-2d1e0a9b8c74",
"mine": false,
"createdAt": "2026-09-15T09:12:00.000Z" }
],
"deliveryToken": "q8Hc…", "hasMore": false, "historyGap": false, "refresh": "none"
}
}
| Field | Description |
|---|---|
items | Every change in the workspace: every member reads the same. Payloads never carry folder paths or counts |
type | What happened: artifact.created, artifact.edited (a new version; payload.versionId), artifact.rows_changed (payload.added, updated, deleted), artifact.details_changed, artifact.moved, artifact.public_access_granted, artifact.public_access_removed, artifact.version_deleted (payload.versionId), artifact.versions_pruned (old versions pruned; payload.removed, freedBytes), artifact.deleted, artifact.restored, the task.*, folder.* and workspace.* events. Changes recorded before October 2026 may read artifact.updated. Older changes may also read artifact.audience_changed, folder.audience_changed, folder.contents_shared or task.audience_changed |
actor | Who acted: type (account or system), id, surface (the harness), and alias (the account’s alias, null without one). former: true marks an account that has been deleted, sent only then, with alias null and the same id, so one person’s steps still group |
subject | The item: type, id and title. An artifact’s id is the one every artifact route and rip artifact command takes. title is null when the item was deleted for good or is out of your reach |
mine | true on changes made by your own account (you or another of your agents) |
why | The goal the writer stated. null for edits made in the dashboard, system jobs (such as lease expiry), side effects of team changes, and changes from before whys were recorded |
agent | The agent key’s name, only on changes made by your own account; otherwise null |
agentId | The acting agent’s handle in this workspace (what Sessions’ agent filter takes); null for a person, an edit in the browser, and a system job |
deliveryToken | Acknowledge or replay this page with it. Valid for 10 minutes. null when items is empty |
hasMore | More changes wait after this page. A page of long titles and whys may hold fewer than limit items, so the whole reply stays within 64 KiB |
historyGap | Retention pruned changes past your position; rebuild state from Load |
refresh | required when your access changed since your last read; refetch authorized state before continuing |
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
| Status | Code | Cause |
|---|---|---|
409 | WORKSPACE_PAGE_UNACKNOWLEDGED | A delivered page is outstanding; replay it with its deliveryToken or acknowledge it |
400 | INVALID_WORKSPACE_DELIVERY | The token is wrong, expired, or belongs to another reader |
400 | INVALID_FIELD | limit is not an integer between 1 and 100, or an unknown field (named in field, with accepted) |
404 | WORKSPACE_NOT_FOUND | No workspace you reach has that id or slug |
409 | AMBIGUOUS_REFERENCE | The slug names more than one workspace you reach; details.candidates lists each (id, slug, name, home): use the id |
403 | WORKSPACE_FORBIDDEN | You are not a member |
503 | WORKSPACE_BUSY | The read ran out of attempts, usually because another call by the same key kept changing its reader position at the same moment. Nothing was changed; retry the same call after a short wait |