# API

**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).

> The control plane's API, spin.v1: every service and procedure, generated from its OpenAPI document.

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

The control plane's API, spin.v1, generated from its protobuf schema. Every procedure is a Connect unary call: POST a JSON body to /&lt;service>/&lt;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`](https://docs.spinbox.dev/openapi.json.md); its sha256 is `openapiSha256` in the site's [`reference.json`](https://github.com/spin-stack/website/blob/main/src/data/reference.json). An error is Connect's: a non-200 status with a JSON body naming a `code` and a `message`.

```sh
curl -s https://app.example.com/spin.v1.WorkspaceService/ListWorkspaces \
  -H 'Content-Type: application/json' -H "Authorization: Bearer $SPIN_TOKEN" -d '{}'
```

## Services

- [PasskeyService](https://docs.spinbox.dev/reference/api/passkeyservice.md): 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](https://docs.spinbox.dev/reference/api/authservice.md): 16 procedures
- [WorkspaceService](https://docs.spinbox.dev/reference/api/workspaceservice.md): 57 procedures
- [SettingsService](https://docs.spinbox.dev/reference/api/settingsservice.md): 6 procedures
- [AdminService](https://docs.spinbox.dev/reference/api/adminservice.md): AdminService manages installation-wide settings, user management, and resource presets. Only accessible to instance administrators.
- [ExecService](https://docs.spinbox.dev/reference/api/execservice.md): 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](https://docs.spinbox.dev/reference/api/forgeservice.md): 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](https://docs.spinbox.dev/reference/api/hostservice.md): 9 procedures
- [HostShellService](https://docs.spinbox.dev/reference/api/hostshellservice.md): 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/&lt;id>/terminal. (internal/hostshell).
- [LogService](https://docs.spinbox.dev/reference/api/logservice.md): 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](https://docs.spinbox.dev/reference/api/projectservice.md): 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](https://docs.spinbox.dev/reference/api/runnertokenservice.md): 4 procedures
- [SetupService](https://docs.spinbox.dev/reference/api/setupservice.md): SetupService handles initial platform setup and admin bootstrap. Most endpoints require admin authentication, except GetSetupStatus and PasswordLogin.
- [ShareService](https://docs.spinbox.dev/reference/api/shareservice.md): ShareService manages snapshot sharing. Snapshots can be shared with specific users or made public. Users can create new workspaces from shared snapshots.
- [SSHKeyService](https://docs.spinbox.dev/reference/api/sshkeyservice.md): 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](https://docs.spinbox.dev/reference/api/teamservice.md): 19 procedures
- [Types](https://docs.spinbox.dev/reference/api/types.md): every message and enum the procedures name
