# WorkspaceService

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://docs.spinbox.dev/reference/status.md); what Spinbox does not do is on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

> spin.v1.WorkspaceService: each procedure, its request and its response.

<!-- Generated by tools/refgen from spin:internal/controlplane/apidocs/spin.v1.openapi.json. Edit the source, not this file. -->

## AddWorkspaceGuest

`POST /spin.v1.WorkspaceService/AddWorkspaceGuest`

Invite a person to log in to a workspace as its guest, by their email: the owner's to ask, with an assertion of a passkey of theirs - a guest is root in the workspace, so a session alone lets nobody in. They log in from then on.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `email` | string |  |
| `stepUp` | [PasskeyAssertion](https://docs.spinbox.dev/reference/api/types.md#passkeyassertion) | An assertion of a passkey of the owner's over a PASSKEY_PURPOSE_ADD_GUEST challenge naming "&lt;workspace_id> &lt;email>". |

**Response**

No fields: `{}`.

## AttachVSCodeServer

`POST /spin.v1.WorkspaceService/AttachVSCodeServer`

Give a running workspace the VS Code server of a client's commit, while it runs: published first when this installation has not got it and an administrator accepted the VS Code server's terms (AdminService.AcceptThirdPartyTerms), refused as FAILED_PRECONDITION, saying so, when nobody did. Asked again until it answers attached.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `commit` | string | commit is 40 hex digits. |
| `publish` | boolean | publish tries a publish of commit again when the last one failed; without it, that failure is the answer. A client sets it on its first ask, and not on those that follow. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `attached` | boolean | attached: the workspace has the server now. Otherwise it is being published, and step says where that is. |
| `step` | string |  |
| `detached` | list of string | detached are the servers the workspace gave up to make room, asked for longest ago. |

## CheckPortAccess

`POST /spin.v1.WorkspaceService/CheckPortAccess`

Whether one request may reach one published port. The gate in front of them.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceName` | string | From the subdomain |
| `port` | integer (int32) |  |
| `sessionToken` | string | The session token as the proxy received it, empty for a request with no session at all. Only a PUBLIC port is reachable that way. |
| `httpsBackend` | boolean | As in OpenWorkspaceProxySessionRequest |

**Response**

| Field | Type | What it is |
|---|---|---|
| `status` | [WorkspaceProxyStatus](https://docs.spinbox.dev/reference/api/types.md#workspaceproxystatus) |  |
| `allowed` | boolean |  |
| `access` | [PortAccess](https://docs.spinbox.dev/reference/api/types.md#portaccess) | What the port's level is, so the proxy can tell a refusal that a login would fix from one it would not: an anonymous request to a PRIVATE port is a redirect, and a signed-in request to the same port is a 403 no amount of signing in changes. |
| `workspaceId` | string | The workspace the name was decided about, when allowed. The proxy pools connections by it and opens sessions for it: a name is freed by a rename and taken by someone else's workspace, and a connection pooled by name would carry the next request into the old one. |
| `sessionRefused` | boolean | The session asked with is no good here: it has ended, or is another workspace's. The proxy drops the cookie, which would otherwise be sent and refused until it expires. |

## CheckPortPublished

`POST /spin.v1.WorkspaceService/CheckPortPublished`

Whether a published port's name is one this installation serves, whoever may reach it: the proxy's on-demand TLS question, asked before any browser has a session to send.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceName` | string | From the subdomain |
| `port` | integer (int32) |  |
| `httpsBackend` | boolean | As in CheckPortAccessRequest: 3000s- is not 3000- |

**Response**

| Field | Type | What it is |
|---|---|---|
| `published` | boolean | The port is published on a workspace that is not deleted, at any level and in any state. |

## CloneWorkspace

`POST /spin.v1.WorkspaceService/CloneWorkspace`

Clone a running workspace: a snapshot of its disk, published, and a workspace created from it with the source's team, project and ref, size, network policies and environment, owned by the caller. Disk only: a clone has an identity of its own, so no memory goes with it. The snapshot stays, as the clone's floor. Answers once the clone exists, which takes as long as publishing the source's disk.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `name` | string | The clone's name; generated when empty. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |
| `snapshot` | [Snapshot](https://docs.spinbox.dev/reference/api/types.md#snapshot) | The source's snapshot the clone was made from, which stays as the clone's floor. |

## CreateSnapshot

`POST /spin.v1.WorkspaceService/CreateSnapshot`

Create a snapshot of the current workspace state

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `description` | string | Optional description |
| `withMemory` | boolean | with_memory keeps the machine's memory too, taken at the instant the disk is sealed; the guest is paused for tens of milliseconds, and the call returns once the memory is written. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `snapshot` | [Snapshot](https://docs.spinbox.dev/reference/api/types.md#snapshot) |  |

## CreateWorkspace

`POST /spin.v1.WorkspaceService/CreateWorkspace`

Create a new workspace

**Request**

| Field | Type | What it is |
|---|---|---|
| `name` | string | Optional, generated if empty |
| `teamId` | string | Optional: team ID (personal workspace if empty) |
| `image` | string | A published image (ListImages); required unless from_snapshot_id is set |
| `preset` | string | The preset it is sized by, by name (AdminService.ListResourcePresets): its cores, memory, disk and how it grows. Empty is the project's preset when project_id names one, otherwise the installation's default preset, or with none marked 1 core, 2048 MB and 10 GB free. A disabled preset is refused. |
| `env` | map of string to string | Environment variables |
| `fromSnapshotId` | string | Create workspace from a shared snapshot |
| `networkTags` | list of string | network_tags are the network policies this workspace runs under, by name - the same idea as a GCP instance's network tags. The host's ruleset names the tag and holds the set of machines carrying it, so this decides which rules apply without naming a rule. Empty runs the workspace under the installation's default, and under "offline" where it declares none: a create that names nothing reaches nothing, rather than everything. A tag the host has no policy for fails the start rather than being ignored: a workspace asking for a policy the node does not have is a question with two answers, and quietly choosing "run it without" is how one ends up less contained than whoever launched it believes. |
| `projectId` | string | A project the caller sees: the workspace is the project's - its image and tags, which the request then names neither of, and its preset unless preset names another - in team_id, the caller's personal team when empty, and its guest clones the project's repository at ref, the project's own when empty. Refused while the repository is on a forge the installation connects to (ForgeService) and the caller has not connected their account there. |
| `ref` | string |  |
| `requestId` | string | Optional, at most 128 bytes: the client's key for this create, so a retry after an answer it never got is answered with the workspace the first attempt made. The same key with another request is refused (FAILED_PRECONDITION). |
| `agentVolumeId` | string | Optional: an agent's home of the caller's to mount (ListAgentVolumes), one no workspace mounts now - the history of a workspace since erased, found again in this one. Empty makes the workspace a new one. Refused while no host has room: a workspace that waits for a host gets its new home when it is placed, and mounts none it was named. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## DeleteAgentVolume

`POST /spin.v1.WorkspaceService/DeleteAgentVolume`

Erase an agent home no workspace mounts: its volume, its key and its bytes.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |

**Response**

No fields: `{}`.

## DeleteSnapshot

`POST /spin.v1.WorkspaceService/DeleteSnapshot`

Delete a snapshot

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `snapshotId` | string |  |

**Response**

No fields: `{}`.

## DeleteWorkspace

`POST /spin.v1.WorkspaceService/DeleteWorkspace`

Delete a workspace: into the trash, where the installation keeps one, or erased.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `force` | boolean | Force delete regardless of state (skips state validation) |
| `permanently` | boolean | permanently erases the workspace now - its disk, snapshots and keys - rather than putting it in the trash; a workspace already in the trash is erased only this way. What is erased cannot be undeleted: the store expires its bytes when its retention ends. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `trashedUntil` | `Timestamp` | Until when it can be undeleted; unset when it was erased. |

## DiffSnapshots

`POST /spin.v1.WorkspaceService/DiffSnapshots`

Compare two of a workspace's snapshots file by file.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `fromSnapshotId` | string | Empty compares from what the workspace was created from. |
| `toSnapshotId` | string |  |
| `under` | string | under narrows the comparison to one path of the filesystem, from its root; empty is all of it. The walk starts there rather than filtering, so what is outside it costs nothing and does not fill the answer. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `changes` | list of [FileChange](https://docs.spinbox.dev/reference/api/types.md#filechange) | Every change from one snapshot to the other, a directory before what is under it. |
| `truncated` | boolean | truncated says there are more changes than one answer carries. |

## ExposePort

`POST /spin.v1.WorkspaceService/ExposePort`

Port exposure

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `port` | integer (int32) |  |
| `httpsBackend` | boolean | See ExposedPort.https_backend |
| `description` | string |  |
| `access` | [PortAccess](https://docs.spinbox.dev/reference/api/types.md#portaccess) | Left unset, this is PRIVATE. Exposing a port is not the same as publishing it. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `exposedPort` | [ExposedPort](https://docs.spinbox.dev/reference/api/types.md#exposedport) |  |

## GetWorkspace

`POST /spin.v1.WorkspaceService/GetWorkspace`

Get a specific workspace

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | Workspace ID or name |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## GetWorkspaceConsole

`POST /spin.v1.WorkspaceService/GetWorkspaceConsole`

The tail of the workspace's serial console: the kernel, vminit, then the supervisor. It is where a machine that never came up says why, and it is read on demand from the host that holds it. An installation that collects consoles also keeps them, searchable for their retention (LogService.SearchWorkspaceLogs); one that does not keeps them on the host, since the console also carries what the tenant's own programs print.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `lines` | integer (int32) | How many lines from the end; zero asks for the default. The host bounds it either way. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `lines` | list of string | Newest last, as the console was written. |
| `truncated` | boolean | truncated says there are lines before the first one here, so what this begins with is not mistaken for the start of the boot. |
| `hostId` | string | Which host answered. A console belongs to the machine that wrote it, and a workspace that has moved has nothing to say about the run that failed on the host it left. |

## GetWorkspaceCost

`POST /spin.v1.WorkspaceService/GetWorkspaceCost`

What the workspace cost in the month in progress and what it costs while it runs, for whoever reads the workspace itself: its owner, and a guest its owner let in. Nobody else is answered - one workspace's cost says how much another person works. Read from the bill as the installation last read it, never from the cloud.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month in progress: its first instant, UTC. |
| `readAt` | `Timestamp` | When the bill was last read; unset where it never was - an installation with no bill scope, a cloud that sends none - and then nothing below is known and nothing is to be drawn. |
| `currency` | string | ISO 4217; every amount here is in millionths of it. |
| `share` | [CostShare](https://docs.spinbox.dev/reference/api/types.md#costshare) | The month so far. |
| `estimate` | [CostEstimate](https://docs.spinbox.dev/reference/api/types.md#costestimate) | Unset where no day before the reading was billed, or none says anything of this workspace. |

## GetWorkspaceDeletion

`POST /spin.v1.WorkspaceService/GetWorkspaceDeletion`

What deleting a workspace would do, asked before it is done: what goes to the trash and for how long, what is erased at once, and what outlives it. It changes nothing.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `permanently` | boolean | What DeleteWorkspaceRequest.permanently would do: an erase, whatever the trash keeps. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `trashDays` | integer (int32) | How many days the delete keeps the workspace in the trash; 0 is an erase now - the installation keeps no trash, or permanently was asked. |
| `effects` | list of [DeletionEffect](https://docs.spinbox.dev/reference/api/types.md#deletioneffect) | Everything the delete does to what the workspace has, ordered erased, trashed, kept. Only what this workspace has: one with no snapshot is told nothing of snapshots. |

## GetWorkspaceEgress

`POST /spin.v1.WorkspaceService/GetWorkspaceEgress`

What a running workspace has actually reached beyond the node.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `destinations` | list of [ObservedDestination](https://docs.spinbox.dev/reference/api/types.md#observeddestination) | Most traffic first, so what an allowlist has to carry is at the top. |
| `lookups` | list of [ResolverLookup](https://docs.spinbox.dev/reference/api/types.md#resolverlookup) | The workspace's recent lookups its host's resolver did not answer as asked, newest first: "it cannot resolve github.com" is an upstream failing, a name pointing into the node being removed, or a query type refused, and this says which. Answered lookups are not kept. |
| `refused` | list of [RefusedDestination](https://docs.spinbox.dev/reference/api/types.md#refuseddestination) | What the host's drops refused the workspace in the last hour, most packets first: the node's own networks, or what none of its policies allows. The other half of destinations, and what a policy that is too narrow looks like from outside the machine. |
| `brokered` | list of [BrokeredRequest](https://docs.spinbox.dev/reference/api/types.md#brokeredrequest) | The workspace's recent requests to names its policies broker with an injection, newest first: what the host's egress proxy set a header on, and what it refused and why. A brokered name no rule injects on is relayed byte for byte and leaves no request here. |

## GetWorkspaceHistory

`POST /spin.v1.WorkspaceService/GetWorkspaceHistory`

Get workspace history (snapshots/state changes timeline)

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `limit` | integer (int32) | Number of events (default: 50) |

**Response**

| Field | Type | What it is |
|---|---|---|
| `events` | list of [WorkspaceEvent](https://docs.spinbox.dev/reference/api/types.md#workspaceevent) |  |

## GetWorkspaceIdentity

`POST /spin.v1.WorkspaceService/GetWorkspaceIdentity`

Who the workspace is outside spin: the identity its tokens and signatures carry, the issuer a relying party trusts it by, and what it was cloned from.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `spiffeId` | string | The workspace's SPIFFE ID, spiffe://&lt;domain>/t/&lt;team>/w/&lt;workspace>: every subject in it is under it - the user's at /u, each agent's at /a/&lt;name> - so a relying party names the workspace by it as a prefix. |
| `userSubject` | string | The workspace user's subject, what its tokens and signatures carry. |
| `issuer` | string | The issuer its tokens name, https://id.&lt;domain>, where the key set and the allowed signers are. |
| `parentSnapshotId` | string | What the workspace was cloned from: the snapshot, and the workspace whose disk it was when that is still there and of the same team. A workspace made from an image is cloned from the image's snapshot, and no workspace's: the snapshot is named and the workspace is empty. |
| `parentWorkspaceId` | string |  |
| `audiences` | list of string | Who the installation gives identities for; empty is anybody. |

## GetWorkspaceStatus

`POST /spin.v1.WorkspaceService/GetWorkspaceStatus`

What every party believes about one workspace, and where they disagree.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `state` | [WorkspaceState](https://docs.spinbox.dev/reference/api/types.md#workspacestate) | What the control plane believes, which is what every other surface shows. |
| `failureReason` | string | Only when state = FAILED |
| `supervisor` | [SupervisorStatus](https://docs.spinbox.dev/reference/api/types.md#supervisorstatus) |  |
| `host` | [WorkspaceHostStatus](https://docs.spinbox.dev/reference/api/types.md#workspacehoststatus) |  |
| `volume` | [WorkspaceVolumeStatus](https://docs.spinbox.dev/reference/api/types.md#workspacevolumestatus) |  |
| `disagreements` | list of [StatusDisagreement](https://docs.spinbox.dev/reference/api/types.md#statusdisagreement) | Where the four disagree, in the order they should be read. Empty means they agree - which is the answer when a workspace is simply healthy, and is worth saying. |
| `runtime` | [WorkspaceRuntime](https://docs.spinbox.dev/reference/api/types.md#workspaceruntime) | What the machine has and uses now, asked of its host. Absent - not zero - when there is no machine to ask about: not running, on no connected host, or a host that did not answer in time. Zero cores would read as a machine that has none. |
| `failure` | [WorkspaceFailure](https://docs.spinbox.dev/reference/api/types.md#workspacefailure) | Which part failed, when state = FAILED; failure_reason is the detail. Workspace.failure. |
| `injections` | list of [InjectionStatus](https://docs.spinbox.dev/reference/api/types.md#injectionstatus) | Each header a brokered rule of the workspace's policies sets, and whether what it is set from is there to set: a request to a brokered name is refused when it is not, and this is where that is seen from outside the machine. |
| `network` | list of [WorkspaceNetworkStatus](https://docs.spinbox.dev/reference/api/types.md#workspacenetworkstatus) | The policies the workspace's network is under (Workspace.network_tags), in their order, and whether each is declared and installed on its host. Empty for a workspace with no tag, which reaches anything beyond its host's own networks. |

## GetWorkspaceUsage

`POST /spin.v1.WorkspaceService/GetWorkspaceUsage`

What the workspace's machine used of what it held, over the last hour at most, as its host sampled it: a running machine's up to now, a stopped or failed one's up to when it ended. The samples live on that host, so the series begins where the machine began there, and goes with a restart of the host, a move, the workspace's next start or its removal.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `windowSeconds` | integer (int32) | How far back: an hour at most, which is all a host keeps; zero is the hour. |
| `stepSeconds` | integer (int32) | How wide each point is: at least 10 seconds, the slowest sampler's period; zero is 10. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `hostId` | string | The host that sampled the series; empty, with no points, when the workspace runs nowhere and its host kept nothing of the machine it ran. |
| `sampledSince` | `Timestamp` | When that host began sampling the machine. Nothing before it is known: the samples are the host's, and a restart of it or a move starts them again. |
| `start` | `Timestamp` | The window the points fall in: step_seconds apart from start, each over the step that begins at its own start. A step with no sample has no point. For a stopped or failed workspace the window ends with the step its machine's last sample fell in. |
| `stepSeconds` | integer (int32) |  |
| `cpu` | list of [CpuUsagePoint](https://docs.spinbox.dev/reference/api/types.md#cpuusagepoint) |  |
| `memory` | list of [MemoryUsagePoint](https://docs.spinbox.dev/reference/api/types.md#memoryusagepoint) |  |
| `network` | list of [NetworkUsagePoint](https://docs.spinbox.dev/reference/api/types.md#networkusagepoint) |  |

## GrantPortAccess

`POST /spin.v1.WorkspaceService/GrantPortAccess`

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `port` | integer (int32) |  |
| `userId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `exposedPort` | [ExposedPort](https://docs.spinbox.dev/reference/api/types.md#exposedport) |  |

## GrantWorkspaceResources

`POST /spin.v1.WorkspaceService/GrantWorkspaceResources`

Give a workspace more cores and memory of its own, up to its preset's ceiling: its host reserves them and its machine is grown while it runs. The grant lasts until it is released or the workspace is deleted.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `cpuCores` | integer (int32) |  |
| `memoryMb` | integer (int32) |  |
| `lasts` | `Duration` | How long the grant lasts before it is given back on its own, from now: at least a minute. Unset keeps it until it is given back. Each grant says it anew: one that says nothing about time is kept, whatever the one before it said. |
| `move` | boolean | move says what to do when a running workspace's host has no room for the grant: move it to a host that has - suspended where it runs, its processes as they are, and resumed there from the checkpoint. The guest is paused from the checkpoint until it runs on the other host, which takes as long as storing its memory and publishing its disk. Without it such a grant is refused. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## KeepWorkspace

`POST /spin.v1.WorkspaceService/KeepWorkspace`

Keep a running workspace awake for a while: neither the idle suspension nor the running cap fires before kept_until, and the question asked before one (suspends_at) is withdrawn. An answer with an end, never permanent: at most a day at a time (MaxKeepMinutes).

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `lasts` | `Duration` | How long from now it is kept awake: a minute to a day. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## ListAgentThreads

`POST /spin.v1.WorkspaceService/ListAgentThreads`

The agent's threads - T3 Code's chats - as the workspace's supervisor last reported them. Titles, paths and times, never a message: the chat itself is read in T3 Code, over the owner's own session (`spin agent`).

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `environmentId` | string | environment_id is T3 Code's id for the workspace's server: a thread's page in its web client is /&lt;environment_id>/&lt;thread id>, served at the port `spin agent` forwards. |
| `threads` | list of [AgentThread](https://docs.spinbox.dev/reference/api/types.md#agentthread) | Newest first. |
| `reportedAt` | `Timestamp` | reported_at is when the supervisor last sent the index; unset where it never has - a workspace that ran no agent. |

## ListAgentVolumes

`POST /spin.v1.WorkspaceService/ListAgentVolumes`

The caller's agent homes: the volume each workspace of theirs mounts at /home/spin-agent-t3, which outlives the workspace - its chats, its sessions - and which another workspace mounts at its creation (CreateWorkspaceRequest.agent_volume_id).

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `volumes` | list of [AgentVolume](https://docs.spinbox.dev/reference/api/types.md#agentvolume) |  |

## ListDeletedWorkspaces

`POST /spin.v1.WorkspaceService/ListDeletedWorkspaces`

The caller's workspaces in the trash, and until when each can be undeleted.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaces` | list of [DeletedWorkspace](https://docs.spinbox.dev/reference/api/types.md#deletedworkspace) |  |
| `trashDays` | integer (int32) | How many days a delete now keeps a workspace here; 0 is no trash, a delete erases. The installation's setting, read by whoever may delete: a delete dialog that could not tell which happens said both, at the one moment the difference matters. |

## ListExposedPorts

`POST /spin.v1.WorkspaceService/ListExposedPorts`

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `ports` | list of [ExposedPort](https://docs.spinbox.dev/reference/api/types.md#exposedport) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |

## ListImages

`POST /spin.v1.WorkspaceService/ListImages`

The images a workspace can actually be created from. A client that offers a name from anywhere else - a constant it ships, a container registry it knows of - offers a create that fails, because a workspace's disk is cloned from a published image and nothing else.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `images` | list of [Image](https://docs.spinbox.dev/reference/api/types.md#image) | One entry per name, newest publication of it, in the order a person reads a list. |

## ListNetworkPolicies

`POST /spin.v1.WorkspaceService/ListNetworkPolicies`

The network policies a workspace can be created with, as the hosts report them.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `policies` | list of [NetworkPolicy](https://docs.spinbox.dev/reference/api/types.md#networkpolicy) |  |
| `hostsEnforcing` | integer (int32) | Of the hosts connected, how many have installed what the installation declares. They are told on their next heartbeat, so the two differ for a moment after an apply - and go on differing when a host cannot install what was declared, which is the thing worth seeing. |
| `hostsConnected` | integer (int32) |  |

## ListOwnAgentThreads

`POST /spin.v1.WorkspaceService/ListOwnAgentThreads`

The caller's own chats across every workspace of theirs, each workspace's as its supervisor last reported them: what the dashboard's chat mode lists in one rail. Selected by the caller's id, never one from the request, and a key bound to a team or projects lists theirs alone.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaces` | list of [WorkspaceAgentThreads](https://docs.spinbox.dev/reference/api/types.md#workspaceagentthreads) | One per workspace of the caller's whose supervisor reported a chat, in project then workspace name order; a workspace in the trash is not here. |

## ListSnapshots

`POST /spin.v1.WorkspaceService/ListSnapshots`

List snapshots for a workspace

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `snapshots` | list of [Snapshot](https://docs.spinbox.dev/reference/api/types.md#snapshot) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |
| `baseSnapshotId` | string | What the workspace's disk is cloned from now: the snapshot last restored to, or the one it was cloned from - for a workspace made from an image, that image's. Empty for a disk that was not cloned. |

## ListWorkspaceGuests

`POST /spin.v1.WorkspaceService/ListWorkspaceGuests`

The people who log in to a workspace besides its owner, oldest invitation first.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `guests` | list of [WorkspaceGuest](https://docs.spinbox.dev/reference/api/types.md#workspaceguest) |  |

## ListWorkspaceQuarantineDenials

`POST /spin.v1.WorkspaceService/ListWorkspaceQuarantineDenials`

What a workspace attempted past its policy: the refusals its supervisor reported, newest first - an administrator's reading of what was tried while it was held.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string | The workspace's id. |
| `limit` | integer (int32) | How many of the newest to answer; the newest first. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `denials` | list of [QuarantineDenial](https://docs.spinbox.dev/reference/api/types.md#quarantinedenial) | Newest first. |

## ListWorkspaceTimeline

`POST /spin.v1.WorkspaceService/ListWorkspaceTimeline`

What happened to a workspace, newest first, between two instants: its own events and what the audit log records of it and its snapshots, each with who did it - for its owner, read as GetWorkspaceHistory is. AdminService.ListTimeline is the same reading of any workspace, a host, a team, a project or the whole installation.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `since` | `Timestamp` | Inclusive; unset reads from as far back as the records go. |
| `until` | `Timestamp` | Exclusive; unset is now. |
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) | page_size is at most 200, and zero is 50. total_count is not counted. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `events` | list of [TimelineEvent](https://docs.spinbox.dev/reference/api/types.md#timelineevent) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |
| `keptDays` | integer (int32) | kept_days is how long what the timeline reads is kept: before it, an empty timeline is the records gone, not nothing having happened. |

## ListWorkspaces

`POST /spin.v1.WorkspaceService/ListWorkspaces`

List workspaces for the authenticated user

**Request**

| Field | Type | What it is |
|---|---|---|
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |
| `stateFilter` | [WorkspaceState](https://docs.spinbox.dev/reference/api/types.md#workspacestate) | Optional filter by state |
| `teamId` | string | Optional filter by team (empty = all user's workspaces) |
| `nameFilter` | string | Optional search by name prefix |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaces` | list of [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |

## MoveWorkspace

`POST /spin.v1.WorkspaceService/MoveWorkspace`

Move a running workspace to another host: suspended where it runs, its processes as they are, and resumed there from the checkpoint, holding what it holds. Placement chooses the host, as it does at a start. A workspace that is not running is refused: placement decides where it runs at its next start.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## OpenWorkspaceProxySession

`POST /spin.v1.WorkspaceService/OpenWorkspaceProxySession`

One connection into a published port, for the proxy, when it needs a new one.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceName` | string | From the subdomain, as CheckPortAccess takes it |
| `port` | integer (int32) | The published port inside the workspace |
| `sessionToken` | string | The session token of whoever the connection is being opened for, validated here. It is the difference between a control plane that can refuse and one that cannot. The proxy gates each request in front, but this is reachable on its own, and without a credential to check, anything that could reach it would open a session into any published port of any workspace. Empty is allowed and reaches only PUBLIC ports. |
| `httpsBackend` | boolean | The hostname's s. A port whose flag differs answers as one that is not exposed. |
| `workspaceId` | string | The workspace CheckPortAccess decided the request about. A name that now names another answers as a port that is not exposed: the session is for the workspace that was decided. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `status` | [WorkspaceProxyStatus](https://docs.spinbox.dev/reference/api/types.md#workspaceproxystatus) |  |
| `relayUrl` | string | Where the two ends of this connection meet, and the token that names it there. Set only when status is ACCESSIBLE. The token is single-use: one connection, one token. |
| `sessionToken` | string |  |
| `httpsBackend` | boolean | The flag of the row the session was authorized on: whether the proxy speaks TLS. |

## QuarantineWorkspace

`POST /spin.v1.WorkspaceService/QuarantineWorkspace`

Hold a workspace in quarantine: an administrator's decision, held until one releases it. A stopped workspace is held at once; one whose machine runs is stopped first, forced, and held when its host says it stopped. Its disk is kept as it was, and meanwhile its own person cannot start, move or delete it.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string | The workspace's id. |
| `reason` | string | What the administrator saw that led to holding it: kept on the audit entry for this act, not on the row. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `name` | string |  |
| `state` | [WorkspaceState](https://docs.spinbox.dev/reference/api/types.md#workspacestate) |  |
| `quarantineHeld` | boolean | Held, as Workspace.quarantine_held: a running workspace answers STOPPING, and this is what says the stop is the quarantine's. |

## RecoverWorkspace

`POST /spin.v1.WorkspaceService/RecoverWorkspace`

Re-home a workspace whose host is gone, at a cost its owner accepts.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `acceptDataLoss` | boolean | False asks what it would cost. True accepts that cost and does it. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `recovered` | boolean | False for a cost report, true when the workspace was re-homed. |
| `unpublishedSeconds` | string (int64) | What recovering costs: the work the dead host had not published, as of its last report, plus the time since - a host that has been silent for an hour has been writing for that hour too, and reporting only what it last said would understate it. |
| `unpublishedBytes` | string (int64) |  |
| `hostLastReportedAt` | `Timestamp` | When that report was made. The two numbers above are only as fresh as this. |
| `newHostId` | string | The host it now runs on. Set only when recovered. |

## ReleaseWorkspaceQuarantine

`POST /spin.v1.WorkspaceService/ReleaseWorkspaceQuarantine`

Release what was quarantined: stopped, with its disk as it was - or, where the stop a quarantine asked for ended FAILED, failed as it is, and no longer held.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string | The workspace's id. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `name` | string |  |
| `state` | [WorkspaceState](https://docs.spinbox.dev/reference/api/types.md#workspacestate) |  |
| `quarantineHeld` | boolean |  |

## ReleaseWorkspaceResources

`POST /spin.v1.WorkspaceService/ReleaseWorkspaceResources`

Give a grant back: the workspace holds its floor again, and its machine is shrunk while it runs.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## RemoveWorkspaceGuest

`POST /spin.v1.WorkspaceService/RemoveWorkspaceGuest`

Take a guest out: the next session they ask for is refused, and the one they hold ends with its certificate.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `userId` | string |  |

**Response**

No fields: `{}`.

## RestoreWorkspace

`POST /spin.v1.WorkspaceService/RestoreWorkspace`

Put a stopped workspace's disk back to one of its snapshots, or to what it was created from.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `snapshotId` | string | One of this workspace's own published snapshots. Empty restores what the workspace was created from - its image's snapshot as it was at creation, not the one the image names now. |
| `withMemory` | boolean | with_memory resumes the snapshot's memory too: the workspace's processes go on from the instant the snapshot was taken, running or stopped before. Only for a snapshot taken with memory; a running workspace is resumed only on its own host. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## RevokePortAccess

`POST /spin.v1.WorkspaceService/RevokePortAccess`

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `port` | integer (int32) |  |
| `userId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `exposedPort` | [ExposedPort](https://docs.spinbox.dev/reference/api/types.md#exposedport) |  |

## SetPortAccess

`POST /spin.v1.WorkspaceService/SetPortAccess`

Who may reach a published port, and who it is shared with.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `port` | integer (int32) |  |
| `access` | [PortAccess](https://docs.spinbox.dev/reference/api/types.md#portaccess) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `exposedPort` | [ExposedPort](https://docs.spinbox.dev/reference/api/types.md#exposedport) |  |

## SetWorkspaceBandwidth

`POST /spin.v1.WorkspaceService/SetWorkspaceBandwidth`

Set what a workspace's network carries each way, an instance admin's to change: the limit bounds the installation's egress bill. A running machine is brought to it where it runs, with its connections open; any other takes it at its next start.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `bandwidthMbps` | integer (int32) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `name` | string |  |
| `state` | [WorkspaceState](https://docs.spinbox.dev/reference/api/types.md#workspacestate) |  |
| `bandwidthMbps` | integer (int32) | Megabits a second each way now in force; zero is unshaped. |

## SetWorkspaceNetworkTags

`POST /spin.v1.WorkspaceService/SetWorkspaceNetworkTags`

Change which egress policies a workspace runs under, while it runs.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `networkTags` | list of string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |
| `droppedConnections` | integer (int32) | dropped_connections is how many of the machine's open connections were cut, because the change took a policy away and what a policy no longer allows must not survive in a socket that was opened before it. Zero when the change only added. |

## SetWorkspaceNetworkWatch

`POST /spin.v1.WorkspaceService/SetWorkspaceNetworkWatch`

Watch where a workspace connects: its host records each lookup, each destination it is let through to and each it is refused, with the time, into the workspace's logs.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `watch` | boolean |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## StartWorkspace

`POST /spin.v1.WorkspaceService/StartWorkspace`

Start a stopped workspace on its own disk, or resume a suspended one from the memory it kept.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `fromDisk` | boolean | Boot a suspended workspace from its disk, dropping the memory it was suspended with: what is left when that memory was taken on a machine no host runs now (WORKSPACE_FAILURE_MACHINE_CHANGED). The guest boots as from a power cut. Refused for a workspace that is not suspended. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## StopWorkspace

`POST /spin.v1.WorkspaceService/StopWorkspace`

Stop a running workspace. Its disk is its volume, kept as it is; no snapshot is taken.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `force` | boolean | Force kill instead of graceful |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## SuspendWorkspace

`POST /spin.v1.WorkspaceService/SuspendWorkspace`

Put a running workspace down with its processes where they are: its memory and its disk are checkpointed and the machine is stopped, and its next start resumes that instant - on any host carrying the same machine. The same thing a drained host does to what it runs. The guest is paused from the checkpoint until it is resumed: it does nothing in between, and nothing it did is given up. Answered once the memory is stored and the disk published. One that fails after the checkpoint lets the guest run on where it was.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |
| `snapshotId` | string | snapshot_id is the checkpoint the next start resumes, and a snapshot like any other: it is listed, it can be restored by name, and deleting it is what makes the workspace start from its disk instead. |

## UndeleteWorkspace

`POST /spin.v1.WorkspaceService/UndeleteWorkspace`

Take a workspace out of the trash, stopped, with its disk and snapshots as they were.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | The workspace's id: a name is not unique among the ones in the trash. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## UnexposePort

`POST /spin.v1.WorkspaceService/UnexposePort`

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `port` | integer (int32) |  |

**Response**

No fields: `{}`.

## UpdateWorkspace

`POST /spin.v1.WorkspaceService/UpdateWorkspace`

Update workspace properties (name, env)

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | Required: workspace ID or name |
| `name` | string | Optional: new name |
| `env` | map of string to string | Optional: replace environment variables |
| `wakeOnAccess` | boolean or null | Note: resource changes require stop/start Optional: Workspace.wake_on_access |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |

## WaitSnapshot

`POST /spin.v1.WorkspaceService/WaitSnapshot`

Wait for a snapshot to be published: until then it cannot be restored, cloned or diffed.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `snapshotId` | string |  |
| `timeoutSeconds` | integer (int32) | At most 600; zero is 300. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `snapshot` | [Snapshot](https://docs.spinbox.dev/reference/api/types.md#snapshot) |  |

## WaitWorkspace

`POST /spin.v1.WorkspaceService/WaitWorkspace`

Wait for a workspace to reach a state: create, start and stop are answered once they are asked for, and this is how a caller learns they are done without polling.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string |  |
| `state` | [WorkspaceState](https://docs.spinbox.dev/reference/api/types.md#workspacestate) |  |
| `timeoutSeconds` | integer (int32) | At most 600; zero is 300. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspace` | [Workspace](https://docs.spinbox.dev/reference/api/types.md#workspace) |  |
