Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

API

View Markdown

The control plane’s API, spin.v1, generated from its protobuf schema. Every procedure is a Connect unary call: POST a JSON body to /<service>/<method> with Content-Type: application/json and Authorization: Bearer &lt;API key>.

Every installation serves the document this reference is made from at https://app.<domain>/openapi.json, and an index of it for a model at /llms.txt. This site serves the same document, of the commit it documents, at /openapi.json; its sha256 is openapiSha256 in the site’s reference.json. An error is Connect’s: a non-200 status with a JSON body naming a code and a message.

Terminal window
curl -s https://app.example.com/spin.v1.WorkspaceService/ListWorkspaces \
-H 'Content-Type: application/json' -H "Authorization: Bearer $SPIN_TOKEN" -d '{}'
  • PasskeyService: PasskeyService is a person’s passkeys: WebAuthn credentials of their account, under the. installation’s base domain (internal/passkey). A passkey signs a challenge the control plane. issued, never a document: what turns a session into a key that logs in (SSHKeyService.AddSSHKey) is an assertion of one, so a session alone - stolen, or an agent’s - is no shell.
  • AuthService: 16 procedures
  • WorkspaceService: 57 procedures
  • SettingsService: 6 procedures
  • AdminService: AdminService manages installation-wide settings, user management, and resource presets. Only accessible to instance administrators.
  • ExecService: ExecService runs commands and moves files in a running workspace, as its root, for a caller who. is no terminal: a program or an agent holding a key with workspace:exec. The control plane logs. in over the same session a terminal’s goes over (a host’s stream from the guest’s vsock, met at. the control plane rather than at the relay) with a certificate of its own for five minutes, and. every call is recorded with who made it and on which credential (audit: workspace_exec).
  • ForgeService: ForgeService is a person’s account on a forge, connected through the installation’s GitHub App. (spin#758): the control plane keeps the token, lists the person’s repositories with it, and a. host’s egress proxy sets it on their workspaces’ brokered requests. No workspace holds it.
  • HostService: 9 procedures
  • HostShellService: HostShellService is a root shell on a host, asked for by an administrator, for a while, with a. reason (spin#712). The host is emptied of its workspaces first - unless the request is an. incident’s, which says so - and retired after, whatever happened in it: once a person has had root. on a host it runs no workspace again. Every session is recorded by the control plane, which. carries it; the terminal itself is a WebSocket at /api/host-shells/<id>/terminal. (internal/hostshell).
  • LogService: LogService is what the installation logged, as its store of logs and traces keeps it. (internal/logstore). Every search is confined by the control plane to what the caller may see; what the caller types is searched inside that and cannot widen it.
  • ProjectService: ProjectService is the installation’s projects (spin#720): a repository and the shape of the. workspace that opens it (CreateWorkspaceRequest.project_id). Anybody signed in makes one where. the installation lets everybody (the setting project_creation), and is its first admin. A project is seen by everybody while it is shared with everyone, and otherwise by its admins and. whom it is shared with; the instance’s admins see and administer every one. Whoever sees one. opens workspaces from it, in a team of theirs.
  • RunnerTokenService: 4 procedures
  • SetupService: SetupService handles initial platform setup and admin bootstrap. Most endpoints require admin authentication, except GetSetupStatus and PasswordLogin.
  • ShareService: ShareService manages snapshot sharing. Snapshots can be shared with specific users or made public. Users can create new workspaces from shared snapshots.
  • SSHKeyService: SSHKeyService is the keys that log in as the person, to every workspace that lets them in: a key. of their own, for good, or a browser’s or a CLI’s enrolled for twelve hours. Each is added with an. assertion of a passkey of theirs (PasskeyService), so a session alone adds none.
  • TeamService: 19 procedures
  • Types: every message and enum the procedures name

Generated by task reference from spin/internal/controlplane/apidocs/spin.v1.openapi.json at 51f7e0dea.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.