Workspaces · Stealth Browser Docs

Workspaces

Project file spaces the agent reads and writes — upload inputs, collect results, download an archive.

What a Workspace is

A project-owned virtual file space. Every Agent session has one: a run's inputs are read from it, and the files the agent produces land in it with the run_id that made them. Several sessions may share a space. Files are objects behind the platform's blob store; no path is ever resolved against a server filesystem.

Routes

Method and path	Input / result
`GET /v1/workspaces`	`{ "data": [Workspace] }`
`POST /v1/workspaces`	`{ "name" }` → Workspace
`GET /v1/workspaces/{id}`	Metadata, `revision`, byte and entry use, limits
`PATCH /v1/workspaces/{id}`	`{ "name", "revision" }`
`DELETE /v1/workspaces/{id}`	`{ "revision" }` → tombstone; `workspace_busy` while a run uses it; owner or admin session
`GET /v1/workspaces/{id}/sessions`	The sessions attached to it
`GET /v1/workspaces/{id}/files`	Files and folders: virtual paths, sizes, revisions, source and run ids
`POST /v1/workspaces/{id}/files`	Raw bytes with the headers below
`POST /v1/workspaces/{id}/folders`	`{ "path", "revision" }`
`PATCH /v1/workspaces/{id}/files/{file}`	`{ "path", "revision" }` — move or rename, folders with their descendants
`POST /v1/workspaces/{id}/delete-files`	`{ "ids", "revision" }` — the entries and their descendants
`GET /v1/workspaces/{id}/files/{file}`	The bytes, as an attachment with the original name
`GET /v1/workspaces/{id}/files/{file}/text`	`{ "file", "text" }` for bounded valid UTF-8 (≤ 64 KiB); otherwise `file_not_text`
`POST /v1/workspaces/{id}/archive`	`{ "ids", "revision" }` → a ZIP

Reading needs read; create, rename, upload and file changes need execute; deleting a whole Workspace needs an owner or admin session.

Uploading

Raw bytes, with the path and the Workspace's current revision in headers:

cURL

curl -X POST "$STEALTH_API_URL/v1/workspaces/$WORKSPACE_ID/files" \  -H "Authorization: Bearer $STEALTH_API_KEY" \  -H "Content-Type: application/octet-stream" \  -H "X-File-Path: input/catalog.csv" \  -H "X-Workspace-Revision: 1" \  --data-binary @catalog.csv

curl -X POST "$STEALTH_API_URL/v1/workspaces/$WORKSPACE_ID/files" \
  -H "Authorization: Bearer $STEALTH_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "X-File-Path: input/catalog.csv" \
  -H "X-Workspace-Revision: 1" \
  --data-binary @catalog.csv

X-File-Path is URI-component encoded (slashes and Unicode included). X-File-Revision is required only when replacing an existing file's content. The response is { "file", "workspace" }.

ws = client.workspaces.create({"name": "Catalog job"})result = client.workspaces.files.upload(ws["id"], "input/catalog.csv", open("catalog.csv", "rb").read())run = client.run("Read input/catalog.csv and write a summary to summary.md.", workspace_id=ws["id"])files = client.workspaces.files.list(ws["id"])for file in files:    print(file["path"], file.get("run_id"))zip_bytes = client.workspaces.files.archive(ws["id"], [f["id"] for f in files])

ws = client.workspaces.create({"name": "Catalog job"})
result = client.workspaces.files.upload(ws["id"], "input/catalog.csv", open("catalog.csv", "rb").read())
run = client.run("Read input/catalog.csv and write a summary to summary.md.", workspace_id=ws["id"])
files = client.workspaces.files.list(ws["id"])
for file in files:
    print(file["path"], file.get("run_id"))
zip_bytes = client.workspaces.files.archive(ws["id"], [f["id"] for f in files])

const ws = await client.workspaces.create({ name: 'Catalog job' });await client.workspaces.files.upload(ws.id, 'input/catalog.csv', await readFile('catalog.csv'));const run = await client.run('Read input/catalog.csv and write a summary to summary.md.', { workspace_id: ws.id });const files = await client.workspaces.files.list(ws.id);for (const file of files) console.log(file.path, file.run_id);const zip = await client.workspaces.files.archive(ws.id, { ids: files.map((f) => f.id) });

const ws = await client.workspaces.create({ name: 'Catalog job' });
await client.workspaces.files.upload(ws.id, 'input/catalog.csv', await readFile('catalog.csv'));
const run = await client.run('Read input/catalog.csv and write a summary to summary.md.', { workspace_id: ws.id });
const files = await client.workspaces.files.list(ws.id);
for (const file of files) console.log(file.path, file.run_id);
const zip = await client.workspaces.files.archive(ws.id, { ids: files.map((f) => f.id) });

The SDKs fetch the revision a write needs when you do not pass one.

Revisions and paths

Every successful change increments the Workspace revision. A stale revision, a name or path collision, or a missing replacement revision answers conflict without touching existing bytes; an existing path is never silently overwritten. Parent folders must exist. Paths are relative NFC UTF-8, at most 512 bytes and 16 segments, with no dot segments, backslashes, control characters, leading or trailing whitespace, or trailing dots.

After a network failure with an unknown outcome, list the files before retrying: uploads do not resume.

Limits

10 MiB and 500 entries per Workspace; 100 retained spaces per project (deleted ones count). Uploads: 10 MiB, 30 seconds, four at once per deployment (upload_busy beyond that). Text preview: 64 KiB. Deleting a space leaves its sessions readable but not continuable; deleting files does not remove copies already in model history.