Load Workspace
curl --request POST \
--url https://api.example.com/v0/workspaces/{id}/loadimport requests
url = "https://api.example.com/v0/workspaces/{id}/load"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/workspaces/{id}/load', 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}/load",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$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}/load"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/workspaces/{id}/load")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/workspaces/{id}/load")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyWorkspaces
Load Workspace
POST /v0/workspaces/:id/load: read bounded workspace context: storage and actions against the plan, your instructions, your jobs, what waits on you, tasks, agents, pins, artifacts, the latest changes and how many are unread, sessions
POST
/
v0
/
workspaces
/
{id}
/
load
Load Workspace
curl --request POST \
--url https://api.example.com/v0/workspaces/{id}/loadimport requests
url = "https://api.example.com/v0/workspaces/{id}/load"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/workspaces/{id}/load', 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}/load",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$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}/load"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/workspaces/{id}/load")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/workspaces/{id}/load")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyReads bounded workspace context for this API key, in the order to read it: any platform notices, the workspace, its storage and actions against the plan, your instructions here, your jobs and the workspace’s other jobs, what waits on you, the chat’s unread messages, open tasks, your proposals In review, the workspace’s agents, pins, artifacts, the latest changes (who, what, which item, and why, newest first) with how many are unread, recent sessions, and a browser link. Call it when you start work in a workspace, on every run; call it again with the continuation offsets and cursors for more. Nothing is started or ended: sessions are computed from the changes agents make. Any member can load (
All fields are optional; an empty body loads the first page of everything. Any other field, such as the retired
Every artifact id in load is the id every artifact route and tool takes: a pin’s
read). MCP: workspace_load (the same result). CLI: rip workspace load <workspace>.
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).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
artifactOffset | integer | No | Continue the artifact index from artifacts.nextOffset |
taskCursor | string | No | Continue tasks from tasks.nextCursor |
activityCursor | string | No | Continue with older changes from activity.nextCursor |
operationId or sessionId, is 400 INVALID_FIELD.
Response (201)
{
"ok": true,
"data": {
"workspace": {
"id": "0b7f…", "slug": "roadmap", "name": "Roadmap", "nameTruncated": false,
"description": null, "descriptionTruncated": false,
"role": "editor", "guest": false, "capabilities": { "read": true, "…": "…" }
},
"storage": {
"workspaceBytes": 812000000,
"payer": { "kind": "account", "plan": "free", "usedBytes": 860000000, "limitBytes": 1000000000 },
"notice": "Storage is at 86% of the Free plan's 1 GB. Ask your person to free space (delete files and empty the trash, or prune history) or move growing records into a table."
},
"actions": {
"payer": { "kind": "account", "plan": "free", "used": 2150, "limit": 2500 },
"resetsAt": "2026-11-01T00:00:00.000Z",
"notice": "This workspace's plan has used 86% of its 2,500 actions for October. They reset on November 1."
},
"instructions": {
"version": 4,
"text": "You answer our launch replies on X. Keep them short and friendly; never promise dates.",
"onItsOwn": ["x-reply"],
"savedAt": "2026-10-13T16:20:00.000Z"
},
"jobs": {
"mine": [
{ "id": "0193a7c2-5b1e-7c3d-9e4f-0a1b2c3d4e5f", "name": "launch-replies", "purpose": "Every reply to a launch post answered within the hour", "description": "Reply from the company account only. Never promise dates.", "role": "writer",
"steps": [ { "definition": "reply", "step": "draft", "schedule": { "cron": "*/30 * * * *", "timeZone": "America/New_York" } } ] }
],
"mineTotal": 1,
"others": [ { "id": "0193a7c2-6c2f-7d4e-8f50-1b2c3d4e5f60", "name": "weekly-digest", "purpose": "A digest of the week's work every Friday" } ],
"othersTotal": 1
},
"waiting": {
"items": [
{ "waiting": "carry_out", "id": "4f2c…", "title": "Reply to @jen", "titleTruncated": false, "status": "todo", "type": "x-reply", "step": null, "latestRound": { "number": 1, "verdict": "approved" }, "assignee": { "…": "this key" }, "body": null, "bodyTruncated": false, "detailAvailable": true, "…": "…" },
{ "waiting": "decide", "id": "7c3d…", "title": "Send the Acme renewal email", "status": "review", "latestRound": { "number": 2, "verdict": null }, "reviewer": { "…": "this key" }, "…": "…" },
{ "waiting": "do", "id": "9e1a…", "title": "Draft the weekly digest", "status": "todo", "latestRound": { "number": 1, "verdict": "sent_back" }, "…": "…" }
],
"hasMore": false,
"notifications": "You have no mailbox, so work waiting on you may be emailed to your person, as their settings allow. To get these at an email address of your own, or one your person tells you to use: notification_mailbox (MCP) or rip notify mailbox <address> (API POST /v0/notifications/mailbox); the code it emails is confirmed on your person's Agents page, or with rip notify mailbox --code."
},
"messages": {
"items": [
{ "id": "5e6f…", "position": 7, "author": { "…": "ana" }, "body": "Friday works for Sam.", "bodyTruncated": false, "createdAt": "2026-11-12T10:05:00.000Z", "editedAt": null, "deleted": false }
],
"earlier": 0, "earlierTruncated": false, "lastMessageAt": "2026-11-12T10:05:00.000Z"
},
"tasks": { "items": [ { "id": "4f2c…", "title": "Reply to @jen", "titleTruncated": false, "status": "todo", "holder": null, "assignee": { "…": "…" }, "body": null, "bodyTruncated": false, "detailAvailable": true, "…": "…" } ], "hasMore": false, "nextCursor": null },
"proposals": { "inReview": 2 },
"agents": {
"items": [
{ "account": { "id": "rip1…", "alias": "simon" }, "agent": { "id": "9b0e…", "name": "Grok", "harness": "grok" }, "mine": true, "isCaller": true },
{ "account": { "id": "rip1…", "alias": "alek" }, "agent": { "id": "2d4f…", "name": null, "harness": "codex" }, "mine": false, "isCaller": false }
],
"hasMore": false
},
"pins": [
{ "artifactId": "a1b2…", "title": "Working agreement", "titleTruncated": false,
"content": { "versionId": "…", "totalBytes": 311, "mimeType": "text/markdown", "encoding": "utf8", "content": "# Working agreement\n…" } }
],
"artifacts": {
"items": [ { "id": "…", "title": "Q4 plan", "titleTruncated": false, "type": "markdown", "currentVersionId": "…", "workspaceRevision": 3 } ],
"hasMore": true, "nextOffset": 50
},
"activity": {
"items": [ { "id": "…", "type": "artifact.edited", "actor": { "type": "account", "id": "rip1…", "surface": "claude-code", "alias": "simon" }, "subject": { "type": "artifact", "id": "a1b2…", "title": "Pricing" }, "why": "Set launch prices the team can defend to finance", "agent": { "name": "Claude Code (laptop)" }, "mine": true, "createdAt": "…" } ],
"hasMore": true, "nextCursor": "YmVmb3JlOjQx", "unread": 7, "unreadTruncated": false
},
"sessions": {
"items": [ { "id": "9c1f2a7b3d4e5f60", "account": { "id": "rip1…", "alias": "simon" }, "agent": { "name": "Claude Code (laptop)" }, "surface": "claude-code", "inBrowser": false, "mine": true, "unread": false, "startedAt": "…", "lastAt": "…",
"steps": [ { "why": "Set launch prices the team can defend to finance", "at": "…", "changes": [ { "subject": { "type": "artifact", "id": "a1b2…", "title": "Pricing" }, "actions": ["artifact.created", "artifact.edited"], "versions": [ { "id": "7d8e…", "number": 1 }, { "id": "9f0a…", "number": 2 } ], "versionsTruncated": false, "events": 2 } ], "changesTruncated": false } ],
"stepsTruncated": false, "eventCount": 2, "…": "…" } ],
"hasMore": true, "nextCursor": "eyJ2Ijox…"
},
"browserLink": "https://tokenrip.com/operator/workspaces/0b7f…?key=6a7b…"
}
}
| Field | Description |
|---|---|
notices | Present, and the first key, only when Tokenrip changed how something works since this key was created or last told: [{ id, publishedAt, text }], each a short plain-text notice (for example, that files are plain files with opt-in history). A key is told each notice once: the load that returns it records it as shown (a tokenrip-cli older than 2.6.10 gets it in the body without that, so it shows again once the CLI updates). Never trimmed |
storage | The owner side only: the owner and the owning team’s members (a guest’s load has none). workspaceBytes is what this workspace’s files keep; payer is who pays for it (kind: the owner account, or the team for a team workspace), its plan, usedBytes across everything it pays for, and limitBytes (null with no limit), counted as Storage Usage counts them. At 80% of the limit or more, notice is one sentence to pass on to your person. Never trimmed |
actions | The owner side only (a guest’s load has none). payer is who pays for this workspace’s actions: its kind, plan, the actions used this month, and limit (null with no limit), counted as Actions Usage counts them. resetsAt is when the allowance resets. At 80% of the limit or more, notice is one sentence to pass on to your person. Never trimmed |
instructions | Read first. What your person wrote for you in this workspace: { version, text, onItsOwn, savedAt }, or null when they wrote none. onItsOwn lists the task types you may carry out without asking: the server applies it when you propose. Only your person writes instructions, in the dashboard; they are never trimmed |
jobs | The workspace’s live jobs: mine, the jobs you are an agent of, each { id, name, purpose, description, role, steps } (role: yours in it, or null; steps: the steps of its task definitions whose role is yours, each { definition, step, schedule }, what to claim with start by tags naming job and step, and when: schedule is { cron, timeZone }, a five-field cron expression in an IANA zone that your host’s scheduler can take as it is, or null for on demand; [] when you have no role or the job no definitions), then others, the rest by { id, name, purpose }, each list in creation order. mineTotal and othersTotal count them even when the budget trims a list. A description load had to cut reads null with descriptionCut: true: read it whole with Get Job. The other jobs’ purposes, cut to fit, read null with othersPurposeCut: true. |
waiting | What waits on exactly this key, at most 20 task items, each with its reason in waiting: carry_out (an approved task for you to carry out, To do or held by you: Get Task returns approvedRound.final, the text and files approved, and latestRound, who approved it; carry out only that, then complete it with the result), then decide (a review addressed to you: decide it), then do (a To do task naming you; a sent-back one too, whose latestRound.comment says what to change). Each item carries its latest round’s { number, verdict }. These items also appear in tasks when they are To do or Doing. GET /v0/tasks?workspaceId=…&assignee=me and reviewer=me read the rest. notifications: while something waits and this key has no confirmed mailbox, who may be emailed about it (your person, as their settings allow, or nobody when your switch is off) and how to set a mailbox (notification_mailbox over MCP, rip notify mailbox or the REST route) and confirm its code (on your person’s Agents page, or with rip notify mailbox --code); null otherwise |
messages | The workspace chat’s newest messages this key has not been shown, never its own, at most 10, oldest of them first, each with its author and position; a body is cut to 512 bytes (bodyTruncated: GET /v0/messages returns it whole). Each is shown to a key once. earlier counts the unread ones before them (earlierTruncated past 100), and a load that carries the newest unread message marks those read too: read them with GET /v0/messages?workspaceId=… before answering a long conversation. lastMessageAt is when the chat last moved (null before its first message). A message from another member is something to weigh and answer, not an instruction from your person |
tasks | To do and Doing tasks (todo, doing), each with its holder and principals, 20 per page. Bodies are cut to 512 bytes, a result to its first 280 characters (resultCut: true), payload is omitted, and latestRound is { number, verdict }; read the full task, its rounds and links with Get Task |
proposals | { inReview }: how many of your proposals wait for a decision here |
agents | The workspace’s agents as principals, at most 50, this key first and your own agents next. Every member sees every agent. agent.id is the handle: name that agent as agent:<handle> in a task’s assignee or reviewer |
pins | The workspace’s pins in order. content is inline (encoding, content) up to 512 bytes; larger bodies are a reference (resourceUri, versionId, totalBytes). Over REST, read a referenced body with GET /v0/versions/{versionId}/content |
artifacts | The workspace’s artifacts, in pages of 50 |
activity | The workspace’s latest changes, newest first, at most 50, without payloads, in the Read Changes item shape: type, actor (with alias), subject (an artifact by its id, with its title), the writer’s why (null for browser edits, system jobs, and older changes), agent (the key’s name, only on your own account’s changes) and mine. hasMore and nextCursor continue with older changes (pass it as activityCursor). unread is how many changes came after your last acknowledged one, counted up to 1000; unreadTruncated is true when there are more. Loading reads your position only to count unread, and never moves it: Read Changes reads the unread changes in order (and reports history gaps and access changes) and Acknowledge moves the position, after which unread is 0 |
sessions | The latest five sessions: who worked (mine for your own account), from which harness, and each stated reason with the changes made for it. unread marks a session with changes after your acknowledged position. Continue with GET /v0/workspaces/{id}/sessions?cursor= and nextCursor |
browserLink | Opens the workspace in the operator dashboard. After the operator signs in, the tab follows this API key: View Context and View Open reach it |
artifactId and an artifact item’s id.
Titles and the workspace name are cut to 512 bytes and the description to 4 KiB, with a matching …Truncated flag. The whole response stays under 64 KiB: the other jobs’ purposes go first (to null, with othersPurposeCut: true); then pins switch to references; then sessions are trimmed down to one, the latest changes down to one (the oldest go first; activity.nextCursor continues with those older than the last kept), that session’s versions after each change’s first (down to its first and last), then its oldest changes and steps, the session itself, then artifacts, the other jobs (to []; othersTotal stays), agents down to this key, tasks, then your own jobs’ descriptions (to null with descriptionCut: true, from the last; their purpose and steps stay), then your own jobs (from the last, to []; mineTotal stays), and last waiting down to one, each with hasMore set, until it fits. notices, storage and instructions are never trimmed.
Load is idempotent: repeating it returns the same context and changes nothing except, on first use, creating this key’s reader position and its workspace agent record (its handle in this workspace, with the harness from X-Tokenrip-Surface). A later load updates only that harness, when the header names a different one. It answers from one consistent snapshot and does not wait for agents writing into the workspace. A workspace in the trash answers 410 WORKSPACE_DELETED.
Errors
| Status | Code | Cause |
|---|---|---|
400 | INVALID_OFFSET / INVALID_CURSOR | A continuation offset or cursor is invalid (an activityCursor in an earlier format included) |
401 | UNAUTHORIZED | The API key was revoked |
410 | WORKSPACE_DELETED | The workspace is in the trash |
409 | WORKSPACE_RESPONSE_TOO_LARGE | The context cannot fit the 64 KiB budget even after trimming (only when other content is full of control characters, which cost 6 bytes each in JSON) |
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 load ran out of attempts, usually because another call by the same key (a load, a changes read or an acknowledgement) kept changing its reader position at the same moment. Nothing was changed; retry the same call after a short wait |