Workspaces

Durable file API over content-addressed object storage — read/write/copy/move, snapshots and zip import/export.

postCopy File

Copies a file or subtree within a workspace. Metadata-only: blobs are shared by content address. overwrite controls replacing an existing destination. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postCreate Upload

Mints a presigned PUT URL (valid 15 minutes) for uploading a zip straight to object storage, plus the matching pull URL to pass as ImportZipHeader.source_url. The filename is reduced to its base name (default upload.zip). Unimplemented unless the workspace store is backed by object storage. **Access:** namespace OPERATOR or above (write)

postCreate Workspace

Creates a durable workspace in a namespace, optionally forking a snapshot (metadata-only). The snapshot must be in the same namespace (PermissionDenied otherwise). **Access:** namespace OPERATOR or above (write); refused for workspace-scoped agent keys

postDelete Snapshot

Deletes a snapshot. NotFound when the id does not name a snapshot (a live workspace cannot be deleted through this call). **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postDelete Workspace

Deletes a workspace and its content. Snapshots cannot be deleted through this call (FailedPrecondition); use DeleteSnapshot. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postExport Zip

Server stream of a workspace subtree as a zip in 64 KiB frames; empty path exports the whole workspace. **Access:** namespace VIEWER or above (read); a workspace-scoped agent key may act only on the trees it was minted for

postGet Workspace

Returns a workspace with derived stats (total bytes, file count, revision). NotFound for an unknown id. **Access:** namespace VIEWER or above (read); a workspace-scoped agent key may act only on the trees it was minted for

postImport Zip

Client stream: one ImportZipHeader, then zip bytes as chunks — or set source_url and the server pulls the zip itself (SSRF-guarded, http(s) only, public addresses only, at most 512 MiB). Unpacks under dest_path; entries escaping the destination are rejected. Returns files and bytes written. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postList Files

Lists the entries under a directory in a workspace or snapshot, optionally recursively. Exactly one of workspace_id / snapshot_id must be set; path is required (use "/" for the root). **Access:** namespace VIEWER or above (read); a workspace-scoped agent key may act only on the trees it was minted for

postList Snapshots

Lists snapshots newest first, either of one workspace (workspace_id) or of a whole namespace (namespace, which includes snapshots whose source workspace was deleted). Exactly one of the two must be set (InvalidArgument). page_size defaults to 100 and is clamped to 1000. **Access:** namespace VIEWER or above (read); the namespace form is refused for workspace-scoped agent keys

postList Workspaces

Lists workspaces in a namespace, most recently updated first. Ephemeral workspaces (owned by a sandbox, job or app replica) are excluded unless include_ephemeral is set. namespace is required unless the caller is a platform admin. page_size defaults to 100 and is clamped to 1000. **Access:** namespace VIEWER or above (read); refused for workspace-scoped agent keys

postMake Directory

Creates a directory (parents = mkdir -p). An existing directory is returned as-is; an existing file is AlreadyExists; a missing parent without parents is NotFound. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postMove File

Renames a file or subtree within a workspace (metadata-only). overwrite controls replacing an existing destination. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postRead File

Server stream of a file's bytes in 64 KiB frames from a workspace or snapshot, with offset/length for partial reads (length 0 = to EOF; an offset past EOF yields a single empty EOF frame). On a miss in a live workspace, flushes that one path out of a mounting sandbox and retries before returning NotFound. Exactly one of workspace_id / snapshot_id must be set. **Access:** namespace VIEWER or above (read); a workspace-scoped agent key may act only on the trees it was minted for

postRemove File

Removes a file or directory (recursive required for a non-empty directory, FailedPrecondition otherwise). The workspace root cannot be removed. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postSet File Attributes

Updates a node's mode, mtime or symlink target; a zero/empty value leaves that attribute unchanged. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postSnapshot Workspace

Freezes a workspace's current content into an immutable snapshot. Flushes any live sandbox holding the workspace first and fails with Unavailable if it cannot, rather than returning a stale snapshot. Returns the snapshot id and full record. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postStat File

Returns metadata for one path in a workspace or snapshot. Exactly one of workspace_id / snapshot_id must be set (InvalidArgument); path is required and is cleaned and rooted, with traversal rejected. **Access:** namespace VIEWER or above (read); a workspace-scoped agent key may act only on the trees it was minted for

postTruncate File

Truncates or zero-extends a file to size bytes. **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postUpdate Workspace

Sets a workspace's label (empty clears it); everything else is immutable. Refused on a snapshot (FailedPrecondition). **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for

postWrite File

Client stream: one WriteHeader first, then data frames. Overwrites (default), appends or patches at an offset, then pushes the change into any live sandbox mounting the workspace. Authorization is checked on the header, before any body is buffered. The body is capped at 64 MiB (InvalidArgument); use CreateUpload + ImportZip for bulk data. Refused on a snapshot (FailedPrecondition). **Access:** namespace OPERATOR or above (write); a workspace-scoped agent key may act only on the trees it was minted for