# AdminService

**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.AdminService: 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. -->

AdminService manages installation-wide settings, user management, and resource presets. Only accessible to instance administrators.

## AcceptThirdPartyTerms

`POST /spin.v1.AdminService/AcceptThirdPartyTerms`

Accept the terms, as the version shown, for the items named: this installation then downloads them - the releases this control plane pins at once, and the newest daily.

**Request**

| Field | Type | What it is |
|---|---|---|
| `termsVersion` | string | The version of the text the administrator was shown: one that is not the current one is refused, so nobody accepts a text they did not read. |
| `items` | list of [ThirdPartyItem](https://docs.spinbox.dev/reference/api/types.md#thirdpartyitem) |  |

**Response**

No fields: `{}`.

## AddAllowedEmail

`POST /spin.v1.AdminService/AddAllowedEmail`

Add allowed email/domain

**Request**

| Field | Type | What it is |
|---|---|---|
| `pattern` | string | Email address (user@example.com) or domain (example.com) |
| `type` | [AllowedEmailType](https://docs.spinbox.dev/reference/api/types.md#allowedemailtype) |  |
| `description` | string | Optional description |

**Response**

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

## ClearUserPasskeys

`POST /spin.v1.AdminService/ClearUserPasskeys`

Clear a person's passkeys, for one who lost them all: their session registers a first again. Their keys and workspaces stay as they are.

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `cleared` | integer (int32) | cleared is how many passkeys the person had. |

## CreateHostClass

`POST /spin.v1.AdminService/CreateHostClass`

**Request**

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

**Response**

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

## CreateNetworkPolicy

`POST /spin.v1.AdminService/CreateNetworkPolicy`

**Request**

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

**Response**

No fields: `{}`.

## CreateResourcePreset

`POST /spin.v1.AdminService/CreateResourcePreset`

Create a resource preset

**Request**

| Field | Type | What it is |
|---|---|---|
| `name` | string | Required: display name |
| `description` | string | Optional: description |
| `cpuCores` | integer (int32) | Required: CPU cores |
| `memoryMb` | integer (int32) | Required: memory in MB |
| `diskGb` | integer (int32) | Required: disk in GB |
| `burst` | [BurstMode](https://docs.spinbox.dev/reference/api/types.md#burstmode) | Required |
| `isDefault` | boolean | Optional: make this the default |
| `enabled` | boolean | Optional: enable the preset (default true) |
| `sortOrder` | integer (int32) | Optional: display order |
| `burstFloorCpuCores` | integer (int32) | Required for a burst mode: what its workspaces start with, at most the preset's size. |
| `burstFloorMemoryMb` | integer (int32) |  |
| `bandwidthMbps` | integer or null (int32) | What a workspace of it may carry each way, in megabits a second. Present, since 0 - unshaped - is an answer; absent, the installation's default. |
| `rpoSeconds` | integer (int32) | How far behind the object store a workspace of it may fall, in seconds; 0 is the installation's. |
| `hostClass` | string | The host class its workspaces run on; empty is the default. |

**Response**

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

## DecideConfigChange

`POST /spin.v1.AdminService/DecideConfigChange`

Apply a change the file proposes, or dismiss it. Either is remembered until the file says something else again. Audited with the admin who decided.

**Request**

| Field | Type | What it is |
|---|---|---|
| `kind` | [ConfigItemKind](https://docs.spinbox.dev/reference/api/types.md#configitemkind) |  |
| `name` | string |  |
| `says` | string | ConfigChange.says, as listed. |
| `apply` | boolean | True writes what the file says; false keeps what the installation has. |

**Response**

No fields: `{}`.

## DeleteHostClass

`POST /spin.v1.AdminService/DeleteHostClass`

**Request**

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

**Response**

No fields: `{}`.

## DeleteNetworkPolicy

`POST /spin.v1.AdminService/DeleteNetworkPolicy`

Refused while a workspace runs under the policy or it is the installation's default.

**Request**

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

**Response**

No fields: `{}`.

## DeleteResourcePreset

`POST /spin.v1.AdminService/DeleteResourcePreset`

Delete a resource preset

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | Required: preset ID to delete |

**Response**

No fields: `{}`.

## ExplainStorageKey

`POST /spin.v1.AdminService/ExplainStorageKey`

What one key in the store is, and whose: a key read off the bucket's console says nothing a person can act on.

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `what` | string | What the object is, in words. |
| `volume` | [StoredVolume](https://docs.spinbox.dev/reference/api/types.md#storedvolume) | Whose it is, when it is a volume's. |

## GetBill

`POST /spin.v1.AdminService/GetBill`

What the installation cost in a month, as its cloud's bill says: by day and service, what the month is forecast to end at, and its budget. As the control plane last read the bill - a few times a day (internal/controlplane/domain/bill) - never the cloud itself, where every question to its billing is billed.

**Request**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month, as any instant in it (UTC's); unset is the month in progress. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month's first instant, UTC. |
| `readAt` | `Timestamp` | When the bill was last read; unset where it never was - no scope (bill_scope), or a cloud that sends none - and then nothing below is known. |
| `currency` | string | ISO 4217; every amount here is in millionths of it. |
| `totalMicros` | string (int64) | The month so far, every day and service. |
| `forecastMicros` | string or null (int64) | What the month is forecast to end at; unset where the cloud has no forecast yet. |
| `budgetLimitMicros` | string or null (int64) | The installation's budget and what the cloud counts against it; unset where it has none. |
| `budgetActualMicros` | string or null (int64) |  |
| `budgetForecastMicros` | string or null (int64) |  |
| `days` | list of [BillDay](https://docs.spinbox.dev/reference/api/types.md#billday) | Oldest first. |

## GetCosts

`POST /spin.v1.AdminService/GetCosts`

A month of the bill shared out to the workspaces that caused it: the runners' by what each workspace held of them, the volumes' bucket by what its volumes kept. What nobody caused is said apart and never spread: the runners' capacity nobody held, the bucket's bytes no workspace keeps, and the platform's own cost by role and service; and, from those, what the installation costs a day with nobody working (internal/controlplane/domain/finops).

**Request**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month, as any instant in it (UTC's); unset is the month in progress. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month's first instant, UTC. |
| `currency` | string | ISO 4217; every amount here is in millionths of it. |
| `workspaces` | list of [WorkspaceCost](https://docs.spinbox.dev/reference/api/types.md#workspacecost) | Costliest first. |
| `idleMicros` | string (int64) | What the runners cost that no workspace held. |
| `unstoredMicros` | string (int64) | What the volumes' bucket cost for bytes no workspace keeps: the images, what nothing references any more. |
| `platform` | list of [PlatformCost](https://docs.spinbox.dev/reference/api/types.md#platformcost) | Every other cost - the control plane, the proxy, keys, logs - by role and service, costliest first. |
| `standby` | [StandbyCost](https://docs.spinbox.dev/reference/api/types.md#standbycost) | What the installation costs a day with nobody working; unset where no day before the reading billed anything. |
| `readAt` | `Timestamp` | When the month's bill was last read; unset where it never was, and then nothing is answered. |
| `trend` | list of [CostMonth](https://docs.spinbox.dev/reference/api/types.md#costmonth) | The year up to this month, oldest first, this month last: each month the bill was read in, shared out as this one is. A month never read is not among them. |

## GetEmailSettings

`POST /spin.v1.AdminService/GetEmailSettings`

The SMTP server the installation tells people through. The password is never read back.

**Request**

No fields: `{}`.

**Response**

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

## GetFleetVersions

`POST /spin.v1.AdminService/GetFleetVersions`

What is running where: this control plane, each host's runner and machine, and the extension releases workspaces are on. An installation is updated in halves, and this is the one page that says which halves it is in.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `controlPlaneVersion` | string |  |
| `machineVersion` | string | The spin-machine release this control plane pins, which a host should be running. |
| `hosts` | list of [FleetHostVersion](https://docs.spinbox.dev/reference/api/types.md#fleethostversion) |  |
| `extensions` | list of [ExtensionVersion](https://docs.spinbox.dev/reference/api/types.md#extensionversion) |  |

## GetInstallationHealth

`POST /spin.v1.AdminService/GetInstallationHealth`

Whether anything is wrong with the installation, in one answer: each part from what the control plane already knows of it - its database, the database's archive, the log store, the collector, its jobs, its hosts and the workspaces waiting for one.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `status` | [HealthStatus](https://docs.spinbox.dev/reference/api/types.md#healthstatus) | status is the worst of the checks'. |
| `checks` | list of [HealthCheck](https://docs.spinbox.dev/reference/api/types.md#healthcheck) | One per part the installation has: a part it does not have - a database archive on a development stack, a log store where none is kept, a collector that never reported, jobs on a control plane that does not lead - is left out rather than answered for. |

## GetMonitoring

`POST /spin.v1.AdminService/GetMonitoring`

The Grafana the control plane serves over the installation's metrics, and the release's dashboards in it.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `grafana` | [Grafana](https://docs.spinbox.dev/reference/api/types.md#grafana) | Unset where the control plane serves none: the installation keeps no metrics, or this machine has no Grafana. |

## GetPlatformImages

`POST /spin.v1.AdminService/GetPlatformImages`

Whether the base image and the supervisor this control plane's image carries are published.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `images` | list of [PlatformImage](https://docs.spinbox.dev/reference/api/types.md#platformimage) | Empty until the object store is configured: there is nowhere to publish to. |
| `baseImages` | list of [BaseImage](https://docs.spinbox.dev/reference/api/types.md#baseimage) | Every base image published, one per machine release, newest first. |
| `supervisorReleases` | list of [ExtensionRelease](https://docs.spinbox.dev/reference/api/types.md#extensionrelease) | Every release of the supervisor, newest first. |
| `agentReleases` | list of [ExtensionRelease](https://docs.spinbox.dev/reference/api/types.md#extensionrelease) | Every release of the agents' programs (Claude Code, Codex and T3 Code, one extension), newest first. |

## GetRunbook

`POST /spin.v1.AdminService/GetRunbook`

One runbook, its markdown and where its file is at the pinned commit. NOT_FOUND for an id this release's runbooks do not have.

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `runbook` | [Runbook](https://docs.spinbox.dev/reference/api/types.md#runbook) |  |
| `markdown` | string | Its body, markdown without the front matter: the app renders it and nothing else (no raw HTML). |
| `sourceUrl` | string | The file at the commit this release pins, to propose a change from. |

## GetSettings

`POST /spin.v1.AdminService/GetSettings`

Every setting of the installation as it is in force, and what each is: its type, its default, its bounds, what it reaches when saved and who writes it (internal/controlplane/settings, the one registry the file, the dashboard and the CLI are made from).

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `values` | map of string to string | Every definition's value in force, by key, as text of its type: what the installation says, or the default where it says nothing. The control plane's own are left out. |
| `definitions` | list of [SettingDefinition](https://docs.spinbox.dev/reference/api/types.md#settingdefinition) | Every setting an administrator is shown, in the registry's order. |
| `runningWorkspaces` | integer (int32) | How many workspaces are running now: what a RUNNING_WORKSPACES setting reaches, and what a NEW_WORKSPACES one leaves as it is. |
| `connectedRunners` | integer or null (int32) | How many runners hold their stream to this control plane now: what a NEXT_HEARTBEAT setting reaches. Unset where this control plane cannot tell. |
| `place` | [InstallationPlace](https://docs.spinbox.dev/reference/api/types.md#installationplace) | Where the installation runs and what it runs, read-only. |

## GetStorageSettings

`POST /spin.v1.AdminService/GetStorageSettings`

Where the installation's object store is. The secret is never read back.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `settings` | [StorageSettings](https://docs.spinbox.dev/reference/api/types.md#storagesettings) |  |
| `volumesExist` | boolean | Whether volumes exist, whose history is in this store: it can then be changed, but not for another bucket or directory. |

## GetStorageUsage

`POST /spin.v1.AdminService/GetStorageUsage`

What the store holds, by what each object is for: every volume's objects and the layers its commits name, with the workspace, image or extension release it is. As the storage-gc job last read it - daily, or when an admin runs it - never the bucket itself.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `volumes` | list of [StoredVolume](https://docs.spinbox.dev/reference/api/types.md#storedvolume) | Heaviest first. |
| `unreferencedLayers` | [StorageTally](https://docs.spinbox.dev/reference/api/types.md#storagetally) | Layers no commit in the store names: the storage GC's to collect. |
| `other` | [StorageTally](https://docs.spinbox.dev/reference/api/types.md#storagetally) | Everything outside volumes/ and layers/: the control planes' claims to lead, the owners' words kept per workspace, the rosters and keyrings, the writers' keys and the identity records. |
| `measuredAt` | `Timestamp` |  |

## GetTelemetryStatus

`POST /spin.v1.AdminService/GetTelemetryStatus`

What the collector has sent and failed to send over its last minute, as the watch on its machine read it from the collector itself.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `reportedAt` | `Timestamp` | Unset: the watch has not reported since this control plane started - no collector, or not yet. |
| `windowSeconds` | integer (int32) | How long the counts below are over. |
| `spans` | [TelemetryFlow](https://docs.spinbox.dev/reference/api/types.md#telemetryflow) | Into the installation's store, after the traces policy chose which to keep. |
| `samples` | [TelemetryFlow](https://docs.spinbox.dev/reference/api/types.md#telemetryflow) | Into the installation's store of metrics. |
| `perVolumeHistograms` | list of string | The metrics that cost most to keep, a histogram per volume, which a surface may offer to drop as one (the setting telemetry_metrics_drop). |

## GetThirdPartyTerms

`POST /spin.v1.AdminService/GetThirdPartyTerms`

The software this installation downloads from its makers, the terms it is used under, and which of it an administrator accepted the terms for: who, when, and which text. Nothing is downloaded of an item whose terms are not accepted (internal/controlplane/thirdparty).

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `termsVersion` | string | The version of the text below, which an acceptance names. |
| `text` | list of string | The terms, a paragraph each. |
| `items` | list of [ThirdPartyTermsItem](https://docs.spinbox.dev/reference/api/types.md#thirdpartytermsitem) |  |

## GetUserWorkspaceEgress

`POST /spin.v1.AdminService/GetUserWorkspaceEgress`

Where a workspace sends, as its owner's GetWorkspaceEgress answers it: the host's counters by destination, nothing of what was carried. Audited, as a reading of somebody else's.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string | The workspace's id. |
| `reason` | string | Why, kept on the audit entry. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `egress` | [GetWorkspaceEgressResponse](https://docs.spinbox.dev/reference/api/workspaceservice.md#getworkspaceegress) |  |

## GetVSCodeServers

`POST /spin.v1.AdminService/GetVSCodeServers`

The VS Code servers workspaces are given (the vscode-server extension): each release, and the publish this control plane ran since it started, if it ran one.

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `releases` | list of [ExtensionRelease](https://docs.spinbox.dev/reference/api/types.md#extensionrelease) | Newest first. |
| `publish` | [VSCodeServerPublish](https://docs.spinbox.dev/reference/api/types.md#vscodeserverpublish) |  |
| `unavailable` | string | Why this control plane cannot publish - no object store, or a build with no machine tools to make the image with - and empty when it can. |

## GetWorkspaceNames

`POST /spin.v1.AdminService/GetWorkspaceNames`

The names of the workspaces ids are, whoever owns them and whatever state they are in, a deleted one among them: a record of the platform's logs names a workspace by its id, and ListWorkspaces is the caller's own. An id the installation no longer holds a row for is left out of the answer.

**Request**

| Field | Type | What it is |
|---|---|---|
| `ids` | list of string | At most 500: the ids a page of records names. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `names` | map of string to string | Each id asked for that the installation holds a row for, to its workspace's name. |

## ListAlerts

`POST /spin.v1.AdminService/ListAlerts`

What the release's alert rules said in the installation's Grafana, newest first: each firing and each resolution the control plane heard, with its runbook and how many administrators it reached.

**Request**

No fields: `{}`.

**Response**

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

## ListAllowedEmails

`POST /spin.v1.AdminService/ListAllowedEmails`

List allowed emails/domains

**Request**

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

**Response**

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

## ListAuditLog

`POST /spin.v1.AdminService/ListAuditLog`

Read the audit log, newest first. There is no RPC that writes one: an entry is written by the operation it records, so a log an API could add to would be one an API could forge.

**Request**

| Field | Type | What it is |
|---|---|---|
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |
| `actorId` | string | Each filter is optional and they are combined with AND; an empty request is the whole log, newest first. |
| `action` | string |  |
| `resourceType` | string |  |
| `since` | `Timestamp` | since bounds the listing at the older end; an audit log is read forward from an incident, and the whole of one is not what a page wants. |
| `excludeActions` | list of string | exclude_actions are actions left out: every sign-in of an installation outnumbers what was done on it, and the one action filter can name what to see but not what to look past. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `entries` | list of [AuditEntry](https://docs.spinbox.dev/reference/api/types.md#auditentry) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |
| `actions` | list of string | actions and resource_types are every value this installation can record, so a reader building a filter does not have to know them. They come from the code rather than from a DISTINCT over the log: the log is the one table that only grows, and a vocabulary that is empty until something happens is a filter that is empty when it matters. |
| `resourceTypes` | list of string |  |
| `totalCapped` | boolean | total_capped says page.total_count is where counting stopped, not the count: the log is counted up to a bound, since counting all of it is reading all of it on every page. |

## ListConfigChanges

`POST /spin.v1.AdminService/ListConfigChanges`

What the config file says now and the installation does not, for an administrator to decide: the file seeds an installation once, and after that its changes are proposals.

**Request**

No fields: `{}`.

**Response**

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

## ListHostClasses

`POST /spin.v1.AdminService/ListHostClasses`

**Request**

No fields: `{}`.

**Response**

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

## ListHostProblems

`POST /spin.v1.AdminService/ListHostProblems`

What is wrong with the fleet's hosts, one problem per host that is not connected or fails a check of its own: the same problems GetInstallationHealth's HOSTS part lists, for the pages that read one host or the fleet and nothing else of the installation.

**Request**

| Field | Type | What it is |
|---|---|---|
| `hostId` | string | The one host asked about; empty for every host of the fleet. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `problems` | list of [Problem](https://docs.spinbox.dev/reference/api/types.md#problem) | At most 20, hosts that are not connected first; problem_count is how many there are. |
| `problemCount` | integer (int32) |  |

## ListJobRuns

`POST /spin.v1.AdminService/ListJobRuns`

One job's runs, newest first.

**Request**

| Field | Type | What it is |
|---|---|---|
| `job` | string |  |
| `limit` | integer (int32) | At most this many, newest first; zero is the default of 50. |

**Response**

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

## ListJobs

`POST /spin.v1.AdminService/ListJobs`

The control plane's periodic work - backups, cleanups, the object store's garbage collection - with how often each runs and how its last run went.

**Request**

No fields: `{}`.

**Response**

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

## ListRefusedVolumes

`POST /spin.v1.AdminService/ListRefusedVolumes`

The disks a host refuses to serve, each with the workspace it is the disk of and whose that is. Audited.

**Request**

No fields: `{}`.

**Response**

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

## ListRekeys

`POST /spin.v1.AdminService/ListRekeys`

The disks being re-keyed, and the ones a revoked host's keys marked for it.

**Request**

No fields: `{}`.

**Response**

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

## ListResourcePresets

`POST /spin.v1.AdminService/ListResourcePresets`

List resource presets

**Request**

| Field | Type | What it is |
|---|---|---|
| `includeDisabled` | boolean | Include disabled presets (admin only) |
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |

**Response**

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

## ListRunbooks

`POST /spin.v1.AdminService/ListRunbooks`

What an operator does when an alert fires, a job fails or an owner is told something went wrong: spin-stack/runbooks at the commit this release pins, served so it is read in the app.

**Request**

No fields: `{}`.

**Response**

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

## ListTimeline

`POST /spin.v1.AdminService/ListTimeline`

What happened, newest first, between two instants, to one workspace, host, team or project, or to the whole installation: read from the audit log, the workspaces' events, the jobs' failed runs and the projects' prebuilds as they are, never copied. Sign-ins and what is done inside a workspace (a session, a command) are the audit log's alone: they outnumber everything else.

**Request**

| Field | Type | What it is |
|---|---|---|
| `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 (ListWorkspaceTimelineResponse). |

## ListUserAPIKeys

`POST /spin.v1.AdminService/ListUserAPIKeys`

List another user's API keys. The secret is never stored, so this is what an admin can know about a key: what it is called, when it was made, when it was last used.

**Request**

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

**Response**

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

## ListUsers

`POST /spin.v1.AdminService/ListUsers`

List all users

**Request**

| Field | Type | What it is |
|---|---|---|
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |
| `query` | string | Optional: filter by name or email |
| `adminsOnly` | boolean | Optional: only return admin users |

**Response**

| Field | Type | What it is |
|---|---|---|
| `users` | list of [User](https://docs.spinbox.dev/reference/api/types.md#user) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |
| `holdings` | map of string to [UserHoldings](https://docs.spinbox.dev/reference/api/types.md#userholdings) | What each listed user still holds, by user id: what an administrator asks before taking access away. Kept off User, which other calls return without it. |
| `refusedRemovals` | map of string to string | Why removing a listed user as an administrator, or disabling them, would be refused, by user id; absent where it would not be. The refusal is the database's (lockout), so a client that never reads this is refused the same. |

## PublishVSCodeServers

`POST /spin.v1.AdminService/PublishVSCodeServers`

Publish the servers of the newest stable VS Code releases, or of the commits named, as a new release. Answers once the publish has begun - it downloads a gigabyte - and GetVSCodeServers says how it goes.

**Request**

| Field | Type | What it is |
|---|---|---|
| `newest` | integer (int32) | The newest stable releases to carry: 2 is the current one and the one before it. |
| `commits` | list of string | Commits to carry besides, each the second line of `code --version`. |

**Response**

No fields: `{}`.

## RecoverUserWorkspace

`POST /spin.v1.AdminService/RecoverUserWorkspace`

Move a workspace off a host that is gone, as its owner's RecoverWorkspace does, and with the same question first: without accept_data_loss it answers what the move would give up and changes nothing. The work given up is its owner's, so a reason is required, kept on the audit entry, and written with who asked on the workspace's history, which its owner reads (WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN). Refused for a workspace held in quarantine.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string | The workspace's id. |
| `acceptDataLoss` | boolean | False asks what it would cost. True accepts that cost, for its owner, and does it. |
| `reason` | string | Why: required, kept on the audit entry and on the workspace's history for its owner. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `recovery` | [RecoverWorkspaceResponse](https://docs.spinbox.dev/reference/api/workspaceservice.md#recoverworkspace) |  |

## RekeyVolume

`POST /spin.v1.AdminService/RekeyVolume`

Re-key a workspace's disk: copy it whole under a key of its own, point the workspace at the copy, and delete the disk - which shreds the key assumed taken and every snapshot of the disk, since those are what that key opens. The workspace must be stopped or quarantined. Refused for a disk something descends from. Audited.

**Request**

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

**Response**

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

## RemoveAllowedEmail

`POST /spin.v1.AdminService/RemoveAllowedEmail`

Remove allowed email/domain

**Request**

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

**Response**

No fields: `{}`.

## RemoveStoredVolume

`POST /spin.v1.AdminService/RemoveStoredVolume`

Remove an image, an extension release, an unclaimed volume or an orphan from the store: its row, then its volume, whose key is shredded; storage-gc collects its layers on its next run. Refused for one that is kept (StoredVolume.kept_because), one placed on a host, and a workspace's disk. Audited.

**Request**

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

**Response**

No fields: `{}`.

## RetryPlatformImages

`POST /spin.v1.AdminService/RetryPlatformImages`

Look again now rather than when the next retry is due.

**Request**

No fields: `{}`.

**Response**

No fields: `{}`.

## RevokeThirdPartyTerms

`POST /spin.v1.AdminService/RevokeThirdPartyTerms`

Take the acceptance back for the items named: nothing more of them is downloaded. What was downloaded already stays until an administrator removes it.

**Request**

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

**Response**

No fields: `{}`.

## RevokeUserAPIKey

`POST /spin.v1.AdminService/RevokeUserAPIKey`

Revoke another user's API key - the offboarding an admin cannot do by asking the user, who may already be gone. It is audited with the admin who did it.

**Request**

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

**Response**

No fields: `{}`.

## RunJobNow

`POST /spin.v1.AdminService/RunJobNow`

Run a job now rather than when it is next due. Refused while it is running: a second run alongside the first would do the same work twice. Audited with the admin who asked.

**Request**

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

**Response**

No fields: `{}`.

## SendTestAlert

`POST /spin.v1.AdminService/SendTestAlert`

Has Grafana test its contact point, which sends a test alert the whole way an alert goes: Grafana, the control plane, an email to every administrator who has not opted out. FAILED_PRECONDITION where this control plane serves no Grafana, or Grafana could not reach the control plane.

**Request**

No fields: `{}`.

**Response**

No fields: `{}`.

## SetSettings

`POST /spin.v1.AdminService/SetSettings`

Writes the settings named, each checked by its definition and all of them together before any is written: a refused one writes nothing.

**Request**

| Field | Type | What it is |
|---|---|---|
| `values` | map of string to string | The settings to write, by key, as text of each one's type. Only ADMIN settings are taken. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `values` | map of string to string | Every value in force once written, as GetSettings answers them. |

## StopUserWorkspace

`POST /spin.v1.AdminService/StopUserWorkspace`

Stop a workspace, as its owner's StopWorkspace does: one whose stop could not publish its disk runs on and holds its host until somebody stops it. Audited.

**Request**

| Field | Type | What it is |
|---|---|---|
| `workspaceId` | string | The workspace's id: an administrator names no workspace of somebody else's by its name. |
| `force` | boolean | Give up what only its host has rather than publish it first, as StopWorkspace's force does. |
| `reason` | string | Why, kept on the audit entry. |

**Response**

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

## UntagImage

`POST /spin.v1.AdminService/UntagImage`

Take a ref off what it names: no new workspace gets those bytes by it, the disks cloned from them go on reading them, and a later publish under the ref tags the new bytes. Audited.

**Request**

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

**Response**

No fields: `{}`.

## UpdateEmailSettings

`POST /spin.v1.AdminService/UpdateEmailSettings`

Set the SMTP server, checked against it - connected to and signed in to - before it is written. An empty host turns email off.

**Request**

| Field | Type | What it is |
|---|---|---|
| `host` | string |  |
| `port` | integer (int32) |  |
| `username` | string |  |
| `password` | string or null | Absent keeps the password there is. |
| `from` | string |  |

**Response**

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

## UpdateHostClass

`POST /spin.v1.AdminService/UpdateHostClass`

**Request**

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

**Response**

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

## UpdateNetworkPolicy

`POST /spin.v1.AdminService/UpdateNetworkPolicy`

**Request**

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

**Response**

No fields: `{}`.

## UpdateResourcePreset

`POST /spin.v1.AdminService/UpdateResourcePreset`

Update a resource preset

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | Required: preset ID to update |
| `name` | string | Optional: new display name |
| `description` | string | Optional: new description |
| `cpuCores` | integer (int32) | Optional: new CPU cores |
| `memoryMb` | integer (int32) | Optional: new memory |
| `diskGb` | integer (int32) | Optional: new disk |
| `burst` | [BurstMode](https://docs.spinbox.dev/reference/api/types.md#burstmode) | Optional: new burst mode |
| `isDefault` | boolean | Optional: make this the default |
| `enabled` | boolean | Optional: enable/disable |
| `sortOrder` | integer (int32) | Optional: new display order |
| `burstFloorCpuCores` | integer (int32) | Optional: new burst floor |
| `burstFloorMemoryMb` | integer (int32) | Optional: new burst floor |
| `bandwidthMbps` | integer or null (int32) | Optional: a new bandwidth. Present, since zero - unshaped - is an answer and not "keep". |
| `rpoSeconds` | integer or null (int32) | Optional: a new RPO. Present, since zero - the installation's - is an answer and not "keep". |
| `hostClass` | string | Optional: a new host class; empty keeps it. Its workspaces made before keep theirs. |

**Response**

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

## UpdateStorageSettings

`POST /spin.v1.AdminService/UpdateStorageSettings`

Set where the object store is, checked against it before it is written; every control plane restarts within seconds to open it. Another store while volumes exist is refused.

**Request**

| Field | Type | What it is |
|---|---|---|
| `bucket` | string |  |
| `endpoint` | string |  |
| `region` | string |  |
| `accessKeyId` | string |  |
| `secretAccessKey` | string or null | Absent keeps the secret there is. |
| `dir` | string |  |
| `principal` | string |  |

**Response**

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

## UpdateUser

`POST /spin.v1.AdminService/UpdateUser`

Update user (can toggle is_instance_admin, disable user)

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | Required: user ID |
| `isInstanceAdmin` | boolean or null | Toggle admin status |
| `disabled` | boolean or null | Disable/enable user |
| `disabledReason` | string or null | Reason for disabling (shown to user) |

**Response**

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