# API

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://spin-stack.github.io/website/reference/status.md); what Spinbox does not do is on [Limitations](https://spin-stack.github.io/website/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://spin-stack.github.io/website/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

- [AuthService](https://spin-stack.github.io/website/reference/api/authservice.md): 15 procedures
- [AdminService](https://spin-stack.github.io/website/reference/api/adminservice.md): AdminService manages installation-wide settings, user management, and resource presets. Only accessible to instance administrators.
- [HostService](https://spin-stack.github.io/website/reference/api/hostservice.md): 8 procedures
- [LogService](https://spin-stack.github.io/website/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.
- [RunnerTokenService](https://spin-stack.github.io/website/reference/api/runnertokenservice.md): 4 procedures
- [SettingsService](https://spin-stack.github.io/website/reference/api/settingsservice.md): 3 procedures
- [SetupService](https://spin-stack.github.io/website/reference/api/setupservice.md): SetupService handles initial platform setup and admin bootstrap. Most endpoints require admin authentication, except GetSetupStatus and PasswordLogin.
- [WorkspaceService](https://spin-stack.github.io/website/reference/api/workspaceservice.md): 49 procedures
- [ShareService](https://spin-stack.github.io/website/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.
- [SignatureService](https://spin-stack.github.io/website/reference/api/signatureservice.md): SignatureService is what only people sign of themselves: who a user's keys are and who a team's. members are. A host holds every workspace's access to these (internal/roster), so a control. plane that is taken can say neither which keys are somebody's nor who is in a team. A. workspace's access is signed through WorkspaceService.SetOwnerWord. The control plane proposes each document from what it holds - a key registered, a member added -. and keeps what was signed; it signs nothing. A client shows a person what they are signing and. signs it with a key of theirs: `spin sign`, with the keys ssh-agent holds, or the terminal's. page, with a passkey.
- [SSHKeyService](https://spin-stack.github.io/website/reference/api/sshkeyservice.md): SSHKeyService is the user's own keys, as a registry: the ones a client offers when the owner. signs a workspace's word (OwnerWord), and the anchor a create may name. A key here logs in to. nothing on its own - only a key the owner's word for a workspace lists does, there.
- [TeamService](https://spin-stack.github.io/website/reference/api/teamservice.md): 27 procedures
- [Types](https://spin-stack.github.io/website/reference/api/types.md): every message and enum the procedures name