chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
---
title: Workspace API
section: Reference
order: 300
summary: The workspace's XRPC methods, its event stream, `/icon` and the page's CSP.
---
HUD is an appview for its workspace, as knotless is for its repositories. Its methods are XRPC at `/xrpc/<nsid>`. Each has a lexicon in `schemas/` (`place.hud.*`, with shared shapes in `place.hud.defs`), and HUD checks the input against it.
What the methods act on is described on [the workspace page](workspace.md).
## Queries
Queries go by `GET`.
| Method | What it does |
| --- | --- |
| `getWorkspace` | Who's signed in, the open tabs, the current canvas, the theme chosen, HUD's themes, and whether to sign in again (`signInAgain`, [sign-in](sign-in.md#signing-in-again)). For the web session, `accounts` lists the other accounts the browser is signed in to ([several accounts](workspace.md#several-accounts)) |
| `listCanvases` | A page at a time. Owned canvases, then shared, then invitations |
| `getCanvas` | A canvas and its tiles in strip order |
| `listThemes` | People's themes, a page at a time. One account's, newest first, or everyone's, as the relay (`HUD_RELAY`) lists the repositories holding them. A theme with a text under 4.5:1 is left out |
| `searchActors` | Accounts whose handle or name starts with what's typed (`q`, `limit` 1 to 10, 6 by default), for the sign-in forms of the page and the iOS app. HUD asks the typeahead service at `typeahead.waow.tech` through its outbound client and keeps only well-formed accounts. Under two letters, or when that service fails, the answer is `{actors: []}` |
| `getPlayground` | What [the playground](playground.md) starts from: the bundled views by id, the component catalog (as `describe_collection` gives it) and HUD's themes. The same for everyone |
| `getAccountData` | What `deleteAccountData` would delete: the canvases the person owns (each with how many others are in it), how many canvases of others they're in, their invitations, their `place.hud.theme` records and whether they chose a theme ([deleting your data](workspace.md#deleting-your-data)) |
| `getLogs` | The lines the server kept (`HUD_LOGS`), for its operators alone (`HUD_OPERATOR_DIDS`): one request's by `trace`, or the last of a `message`, a `level` or a `minMs`, at most 500 (`limit`). Anyone else gets `Forbidden`, and a server keeping none answers `NotFound` ([observability](observability.md#reading-the-kept-lines)) |
## Procedures
Procedures go by `POST`.
| Method | What it does |
| --- | --- |
| `createCanvas` | Makes a canvas of the person's, opened as the last tab and made current |
| `updateCanvas` | Renames a canvas. Only its owner can |
| `deleteCanvas` | Deletes a canvas for every member, and it leaves their tabs. Only its owner can |
| `openCanvas` | Opens a canvas as the last tab and makes it current (one open already just becomes current). It accepts an invitation |
| `closeCanvas` | Closes a tab and keeps the canvas with its members and tiles. The last open tab isn't closed. Closing the current one makes its neighbour current |
| `setTabOrder` | Puts the tabs named first, in that order, then the rest as they were |
| `setTheme` | Draws the person's workspace in a theme: one of HUD's by key, or anyone's `place.hud.theme` by URI, its colours copied as they are now. With neither, the system's light or dark. Their other pages and apps are told |
| `createTheme` | Writes a `place.hud.theme` record in the person's own repository, for anyone to choose. It doesn't choose it |
| `deleteTheme` | Deletes one of the person's own themes. Those who chose it keep its colours |
| `checkTheme` | Says which texts of a palette read at under 4.5:1 on what they're drawn on. It writes nothing |
| `declineInvite` | Turns down an invitation, so the person is no longer a member |
| `inviteMember` | Invites an account by handle or DID as an editor or a viewer. Only the owner can |
| `setMemberRole` | Makes a member an editor or a viewer. Only the owner can, and never for their own role |
| `removeMember` | Takes a member or an invitation off a canvas, and it leaves their tabs. Only the owner can |
| `leaveCanvas` | Leaves a canvas shared with the person. The owner can't leave, so they delete it |
| `addTile` | Adds a tile, placed by the server, or answers the tile already there with the same call ([placing tiles](workspace.md#placing-tiles)) |
| `removeTile` | Takes a tile off. If it heads a column, the next in its stack heads it |
| `placeTile` | Moves a tile right before or after another. Within one column it moves in its stack, else its column moves beside the other's and a stacked tile becomes a column of its own |
| `setTileWidth` | Changes the width of a tile's column. A stacked tile's width is its head's, and the answer is the head |
| `stackTile` | Stacks a tile at the end of another's column (3 tiles at most). A column's head brings the tiles under it along |
| `unstackTile` | Takes a stacked tile out as a column of its own, right after its old one |
| `updateTile` | Changes a tile's title, or its call as a tab chosen in it. The tile stays in place and every page is told. A title made from the call follows the new call, and a given one stays |
| `callTool` | Calls any of HUD's tools but the canvas ones, as the person. Its answer is the `CallToolResult` that `/mcp` gives. An app's call by Bearer gives `kit` (`{ platform, version }`), the renderer drawing it, and its tree is fitted to that kit, else to the oldest ([old builds and new views](views.md#old-builds-and-new-views)). The page's is fitted to this HUD's version |
| `previewView` | Draws a view being written, for [the playground](playground.md). It takes `tool` (`list_records`, `get_record` or `query`) and `arguments` with the view in them. An invalid view answers `{problems: [{at, message}]}`, every problem, and nothing is read. Given `answer` (the `structuredContent` that call read before), it answers `{ui}`, the view drawn over it. Otherwise it makes the call and answers `{result}`. Its input can be up to 4 MiB |
| `uploadBlob` | Uploads an image (JPEG, PNG, WebP or HEIC, at most 2,000,000 bytes) to the person's PDS as their blob, for a record they write next, such as a post's images or a gallery's photos |
| `deleteAccountData` | Deletes everything HUD keeps of the person and ends every session of theirs ([deleting your data](workspace.md#deleting-your-data)). The input names their own DID, else `403`. Only the page's cookie or HUD's own app's token may call it: another MCP client's token gets `403`. With the cookie, the browser goes on as `POST /workspace/signout` leaves it |
## Views and errors
A canvas comes back as a `canvasView`. It holds the `place.hud.canvas` record, the members, the tile count, the storage and the viewer's role.
A tile comes back as a `tileView`. It holds the `place.hud.tile` record as kept, the author, the record's URI where the canvas is in a space, and `icon`.
A failure is `{error, message}`, with one of these errors: `NotFound`, `Forbidden`, `InvalidRequest`, `LimitReached`, `AuthRequired`, `UpstreamFailure` (`uploadBlob`'s PDS failed, or `deleteAccountData` couldn't delete something), `LogsUnreadable` (`getLogs` couldn't read the kept lines).
## Authentication
A method is called as the web session (with its cookie), or with a HUD access token as `Bearer` (the one an MCP client has). A procedure called with the cookie must carry `X-HUD: 1` and the server's own `Origin`, else it gets `403`. `searchActors`, `getPlayground` and `previewView` need no session. `previewView` calls as the account when a session is good, and as no one otherwise. These three answer with sign-in off too, and every other method then answers `MethodNotImplemented`.
With `HUD_WORKSPACE=off` ([running HUD](running.md#environment-variables)) there's no workspace, so only the methods an app's own pages call answer: `searchActors`, `uploadBlob`, `getLogs`, `getAccountData` and `deleteAccountData`. Every other method answers `MethodNotImplemented` (501).
## Event stream
`getWorkspaceEvents` is one stream of server-sent events per person. It isn't an XRPC subscription, since it keeps no history to resume from. It covers every canvas the person has open and follows the tabs as they open and close.
Each `data:` is a JSON object typed by its `$type`:
| `$type` | Shape |
| --- | --- |
| `defs#tileEvent` | `{ canvas, op: add \| update \| remove, key, tile?, by: { did, handle?, kind: person \| agent } }` |
| `defs#presenceEvent` | `{ canvas, present: [{ did, handle }], by }` |
| `defs#canvasesEvent` | The workspace changed, so read it again |
The server sends a `ping` every 25 s. The stream ends when the server stops, and the page connects again.
## /icon
`GET /icon/<domain>` answers with an app's icon. HUD serves it with sign-in off too, since profiles draw apps' icons. The icon is the site's favicon as `HUD_FAVICONS` answers it, a PNG of at most 100 KB.
| Case | Answer | Kept |
| --- | --- | --- |
| An icon | the PNG | a week |
| A domain with none | `404` | a day |
| The service has no answer now | `502` | by no one |
## Page CSP
The page's CSP lets it reach only the server. It loads images and audio from the server and from the origins the bundled views trust, and images from the image CDN. It plays video from Bluesky's video service and CDN too.