# HTTP API

- URL: https://getroomi.com/docs/api
- Built: 2026-10-26

The platform API is what the app, `roomi` and the connector all call: one
contract, checked on both sides, so none of them can do what the API does not
allow. You can call it too, from a script or your own tool. This page says
how to sign in, how requests and replies are shaped, how an upload works, and
lists every endpoint.

## Base URL

```text
https://api.getroomi.com
```

Every endpoint is under `/api`. `GET /healthz` answers
`{"ok":true,"service":"platform"}` without signing in, for a check that the
platform is up.

## Authentication

Every endpoint needs you signed in, except sign-in itself under `/api/auth/`
and the community's public pages. Without a session, an endpoint answers
`401` with `{"error":"sign in first"}`.

There are two ways to be signed in:

- **A cookie**, which the app uses. Signing in to the app sets it.
- **A bearer token**, which `roomi` uses, sent as `Authorization: Bearer
  <token>`: the session `roomi login` keeps, or an API token.

To call the API from a script or CI, make an [API token](https://getroomi.com/docs/cli#api-tokens)
in the app (**Settings → Claude & CLI → API tokens**) and send it as the
bearer:

```sh
curl -s https://api.getroomi.com/api/projects \
  -H "Authorization: Bearer $ROOMI_TOKEN"
```

An API token acts as you in the workspace you made it in, and reaches the
routes `roomi` uses: projects, uploads, builds and their logs, links, what
viewers did and said, changing a project, and the community. Anywhere else, the
plan and billing, your account, the team, tokens themselves, deleting a
project, it is refused with `403` and `"reason":"token"`. Revoked, expired, or
once you leave that workspace, it is answered as no one, `401`. It is shown
once, when it is made; only its hash is kept.

On your own machine you can also sign in with [`roomi login`](https://getroomi.com/docs/cli#roomi-login)
and read that session's header with [`roomi auth header`](https://getroomi.com/docs/cli#roomi-auth-header):

```sh
curl -s https://api.getroomi.com/api/projects \
  -H "$(roomi auth header | jq -r '"Authorization: " + .Authorization')"
```

That token is your session: it is as good as your password until it expires
or you run `roomi logout`, which ends it on the platform. Keep it out of files, logs and
the repository. A token the connector was issued for Claude is refused here,
and a token from `roomi login` is refused by the connector: each is good for
one thing only.

## Workspaces

Every endpoint acts on the **active workspace** of the session: the workspace
the session has active, or, for a session that has none, the first workspace
the person joined. An API token's workspace is always the one it was made in. There is no workspace in the path. A person who
belongs to no workspace is treated as signed out.

An id from another workspace is a `404`, exactly as an id that does not
exist, so the API never says whether something exists elsewhere.

## Requests and replies

- **Bodies are JSON.** Send `Content-Type: application/json`. A body that does
  not fit the endpoint's schema is refused with `400`, `{"error":"invalid"}`,
  and an `issues` list naming each field that does not fit. Fields an
  endpoint does not name are ignored.
- **Replies are JSON**, checked against the contract before they leave, so a
  reply always has the shape listed below.
- **Status codes.** A `GET` answers `200`. A `POST` that creates something
  (`createProject`, `createBuild`, `createLink`) answers `201`; other `POST`s
  answer `200`. The upload's `PUT` answers `204` with no body.
- **Ids** are strings, UUIDs today. Store them as they are; do not rely on
  their format.
- **Times** are ISO 8601 strings in UTC, such as `2026-09-28T14:03:11.000Z`.
  A time that does not apply, such as the expiry of a link that never
  expires, is `null`.
- **Days** in the analytics paths are UTC dates written `YYYY-MM-DD`, both
  ends included.
- **Lists** are returned whole. There is no pagination.

## Errors

A refusal is a status and a JSON body whose `error` says what, in words you
can show a person, and usually a `reason` a program can act on:

```json http
{ "error": "refused: taken", "reason": "taken" }
```

| Status | Means |
|---|---|
| `400` | The body does not fit the schema (`invalid`, with `issues`). |
| `401` | Not signed in (`sign in first`). |
| `402` | A plan's limit. The body names the `limit`, the `plan`, and the plan that would allow more as `upgrade`. |
| `404` | Not found in your workspace (`not found`). |
| `409` | The name is taken (`reason: taken`). |
| `411` | An upload was sent without `Content-Length`. |
| `422` | Refused on its merits (`refused: <reason>`). |
| `423` | The project or workspace is paused (`reason: paused`). |
| `429` | Too many reports in a day (`reason: rate`). |
| `500` | The platform's own fault (`internal error`). |
| `503` | A feature that is not switched on (`reason: unavailable`). |

[Errors](https://getroomi.com/docs/errors#api-refusals) lists every `reason` and what to do about
it.

## Limits

The API has no request rate limit of its own. What limits you is your plan:
the number of projects, deploys in any 24 hours, private links, viewer-hours
and analytics, each refused with a `402` that says which. The largest upload
the platform accepts is 512 MB. See [Plans and limits](https://getroomi.com/docs/plans).

## Deploying through the API

A build is uploaded in three calls, then made live. This is what `roomi
deploy --commit` does, and the `deploy_static` tool.

**1. Start an upload.** Declare the build's kind and its exact size in bytes:

```http
POST /api/projects/{projectId}/uploads
Content-Type: application/json

{"kind":"static","sizeBytes":20480}
```

```json http
{ "uploadId": "e4b7c2a1-9f3d-4c68-a5e1-0d8b6f2c9a37", "putUrl": "/api/uploads/e4b7c2a1-9f3d-4c68-a5e1-0d8b6f2c9a37" }
```

**2. Send the bytes** to `putUrl`, on the API's own address, signed in the
same way. `Content-Length` must be the size you declared; what is stored is
measured again and refused if it differs. An upload takes its bytes once.

```http
PUT /api/uploads/e4b7c2a1-9f3d-4c68-a5e1-0d8b6f2c9a37
Content-Type: application/gzip
Content-Length: 20480
```

It answers `204`.

**3. Register the build** with the upload and its `pitch.json`:

```http
POST /api/projects/{projectId}/builds
Content-Type: application/json

{"uploadId":"e4b7c2a1-9f3d-4c68-a5e1-0d8b6f2c9a37","manifest":{…},"note":"New onboarding flow"}
```

It answers `201` with the build, which is not live yet. A static build is
unpacked here, and refused if its archive is not one the platform will serve.
The deploy counts against your plan's deploys at this step.

**4. Make it live:**

```http
POST /api/projects/{projectId}/builds/{buildId}/live
```

The same call makes an earlier build live again, which is how a rollback is
done.

What the artefact is:

- **A static build**: a gzipped tar of the built folder, with `index.html` at
  its root. At most 5,000 files, 32 MB a file and 256 MB unpacked; files and
  folders only, no links.
- **A container build**: the bundle `roomi deploy` makes from your image. Its
  manifest must carry `run`, the start command `roomi deploy` reads from the
  image, so a container build is deployed with `roomi deploy`, not by hand.

## Endpoints

Every endpoint, drawn from the contract the platform checks each request and
reply against. Paths show parameters as `:name`.

## Projects, builds and links

The core of the contract: projects, uploads and builds, viewer links, and what viewers did and said. `roomi` and the connector call these.

### listProjects

`GET /api/projects`

Every project in your workspace that has not been deleted, newest first, each with its room’s address. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `slug` | `string` | required · 3–40 characters |
| `name` | `string` | required |
| `visibility` | `"private" \| "public"` | required |
| `liveBuildId` | `string \| null` | required |
| `previewBuildId` | `string \| null` | optional |
| `roomUrl` | `string (uri)` | required |
| `createdAt` | `string (date-time)` | required |

### createProject

`POST /api/projects`

Creates a project. Its `slug` is the room’s address; its `name` is what the room shows. Refused with `409` when the slug is taken or was deleted less than 30 days ago, `422` when it is not one the platform allows (`format`, `reserved`, `impersonation`, `banned`), and `402` beyond the plan’s projects.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `slug` | `string` | required · 3–40 characters |
| `name` | `string` | required · 1–80 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `slug` | `string` | required · 3–40 characters |
| `name` | `string` | required |
| `visibility` | `"private" \| "public"` | required |
| `liveBuildId` | `string \| null` | required |
| `previewBuildId` | `string \| null` | optional |
| `roomUrl` | `string (uri)` | required |
| `createdAt` | `string (date-time)` | required |

### getProject

`GET /api/projects/:projectId`

One project of your workspace, by id. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `slug` | `string` | required · 3–40 characters |
| `name` | `string` | required |
| `visibility` | `"private" \| "public"` | required |
| `liveBuildId` | `string \| null` | required |
| `previewBuildId` | `string \| null` | optional |
| `roomUrl` | `string (uri)` | required |
| `createdAt` | `string (date-time)` | required |

### projectAllowance

`GET /api/allowance/projects`

Whether `createProject` would make a new project now: the projects your workspace holds, paused ones included, the most its plan allows (`null` for no limit), and the refusal `createProject` would give, in its words, or `null`. `roomi deploy` and the connector’s `deploy_static` ask it when they rehearse a deploy to a new address. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `used` | `integer` | required |
| `allowed` | `integer \| null` | required |
| `refusal` | `string \| null` | required |

### startUpload

`POST /api/projects/:projectId/uploads`

Declares a build’s artefact before it is sent: its `kind` and its exact size in bytes, at most 512 MB. Returns the upload’s id and the address to `PUT` the bytes to, with `Content-Length` equal to the size declared; that `PUT` answers `204`, and is refused if the size differs.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `kind` | `"container" \| "static"` | required |
| `sizeBytes` | `integer` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `uploadId` | `string` | required · not empty |
| `putUrl` | `string` | required |

### createBuild

`POST /api/projects/:projectId/builds`

Registers a build from a finished upload on the same project, with its `pitch.json`. The build is not live until `makeLive`. A static build is unpacked here; a container build must carry `run`. Refused as `unfinished`, `kind`, `used` or `archive`, with `402` beyond the plan’s deploys and `423` while the platform has the project paused. `rehearsal`, optional, is what the deploy saw rehearsing each story step; the app shows a build without one as not reported, never as passed.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `uploadId` | `string` | required · not empty |
| `manifest` | `object` | required |
| `note` | `string` | optional · at most 200 characters |
| `rehearsal` | `object` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `projectId` | `string` | required · not empty |
| `kind` | `"container" \| "static"` | required |
| `manifest` | `object` | required |
| `sizeBytes` | `integer` | required |
| `note` | `string \| null` | required |
| `live` | `boolean` | required |
| `preview` | `boolean` | optional |
| `createdAt` | `string (date-time)` | required |
| `room` | `"standard" \| "immersive"` | optional |

### listBuilds

`GET /api/projects/:projectId/builds`

Every build of the project, newest first, each saying whether it is the live one. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `projectId` | `string` | required · not empty |
| `kind` | `"container" \| "static"` | required |
| `manifest` | `object` | required |
| `sizeBytes` | `integer` | required |
| `note` | `string \| null` | required |
| `live` | `boolean` | required |
| `preview` | `boolean` | optional |
| `createdAt` | `string (date-time)` | required |
| `room` | `"standard" \| "immersive"` | optional |

### makeLive

`POST /api/projects/:projectId/builds/:buildId/live`

Makes one of the project’s builds the live one, the build its room shows. The same call makes an earlier build live again, which is a rollback (`roomi rollback`), and makes the build being previewed live, which ends the preview. Who did it and when is recorded.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `buildId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `projectId` | `string` | required · not empty |
| `kind` | `"container" \| "static"` | required |
| `manifest` | `object` | required |
| `sizeBytes` | `integer` | required |
| `note` | `string \| null` | required |
| `live` | `boolean` | required |
| `preview` | `boolean` | optional |
| `createdAt` | `string (date-time)` | required |
| `room` | `"standard" \| "immersive"` | optional |

### buildLogs

`GET /api/projects/:projectId/builds/:buildId/logs`

What a container build’s running copies wrote to standard output and standard error, oldest first, with the viewer whose copy wrote each line, redacted of anything that looks like a secret. Each copy keeps its newest 2,000 lines while it runs and none once it stops; `said` says why there are none. Pass the reply’s `cursor` back as `?after=` for the lines written since. A static build has none. Another workspace’s build is `404`. Changes nothing, and does not keep a copy awake.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `buildId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `buildId` | `string` | required · not empty |
| `kind` | `"container" \| "static"` | required |
| `running` | `integer` | required |
| `lines` | `object[]` | required |
| `cursor` | `string` | required |
| `said` | `string \| null` | required |

### previewBuild

`POST /api/projects/:projectId/builds/:buildId/preview`

Makes one of the project’s builds its preview: it does not go live, and no viewer link, public address or Community card shows it. The project’s members see it through the members’ preview (`previewPass`) until `makeLive` makes it live or `endPreview` ends it; a newer preview replaces it. Refused with `422` as `live` for the build that is live already. Recorded in the project’s history.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `buildId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `projectId` | `string` | required · not empty |
| `kind` | `"container" \| "static"` | required |
| `manifest` | `object` | required |
| `sizeBytes` | `integer` | required |
| `note` | `string \| null` | required |
| `live` | `boolean` | required |
| `preview` | `boolean` | optional |
| `createdAt` | `string (date-time)` | required |
| `room` | `"standard" \| "immersive"` | optional |

### endPreview

`POST /api/projects/:projectId/preview/end`

Ends the preview: the members’ preview shows the live build again. The build stays in the project’s builds. Refused with `422` as `no-preview` when nothing is being previewed. Recorded in the project’s history.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `slug` | `string` | required · 3–40 characters |
| `name` | `string` | required |
| `visibility` | `"private" \| "public"` | required |
| `liveBuildId` | `string \| null` | required |
| `previewBuildId` | `string \| null` | optional |
| `roomUrl` | `string (uri)` | required |
| `createdAt` | `string (date-time)` | required |

### createLink

`POST /api/projects/:projectId/links`

Makes a private link to the room for one named viewer, with their email if you give it and an expiry of 1 to 365 days if you want one. Nothing is sent to the email unless you also give `send: true`: then the platform emails the viewer their link on your behalf, from its own address, naming you by the name you chose (and your team, from a team’s workspace), once. The reply carries the link’s full address; no list does, and `revealLink` returns it again. Refused with `402` on a plan without private links, beyond the plan’s links per project, or once the month’s viewer-hours are used; with `send`, refused whole, nothing made, as `send` (`422`) when a safeguard says no, and with `429` past the workspace’s emailed links for the hour or the day. A link that was emailed lists when (`emailedAt`).

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `viewerName` | `string` | required · 1–80 characters |
| `viewerEmail` | `string (email)` | optional |
| `expiresInDays` | `integer` | optional · 1–365 |
| `send` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `link` | `object` | required |
| `url` | `string (uri)` | required |

### rehearseLink

`POST /api/projects/:projectId/links/rehearsal`

What `createLink` would do with the same body, with nothing made or sent: every check it makes and, with `send: true`, every safeguard its email must pass, then who the email would say it is from and its subject. Refused exactly as `createLink` would be. A connection that may only read is refused with `403`, as for every POST.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `viewerName` | `string` | required · 1–80 characters |
| `viewerEmail` | `string (email)` | optional |
| `expiresInDays` | `integer` | optional · 1–365 |
| `send` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `viewerName` | `string` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `email` | `object \| null` | required |

### listLinks

`GET /api/projects/:projectId/links`

Every link of the project, each with its stage in the pipeline and whether its address can be shown again (`recoverable`), never the address. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |

### revokeLink

`POST /api/links/:linkId/revoke`

Revokes a link: it stops opening the room at once, and cannot be opened again. What its viewer already did stays on record.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |

### revealLink

`POST /api/links/:linkId/reveal`

A link’s full address again, to copy and resend when the viewer has lost it. Recorded in the project’s history with who asked. Refused with `422` as `revoked` or `expired` when the link no longer opens the room, and as `unrecoverable` for a link made before 1 October 2026, when only a hash of its key was kept: reissue that one. A connection that may only read is refused with `403`, because the address opens the room. Sent with `Cache-Control: no-store`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `link` | `object` | required |
| `url` | `string (uri)` | required |

### reissueLink

`POST /api/links/:linkId/reissue`

A new address for the same link: the same viewer, with their visits, answers and comments, under a new key. The old address stops opening the room the moment it lands. For a link made before addresses were kept, or one that has gone astray; refused as `revoked` or `expired` like `revealLink`. Recorded in the project’s history.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `link` | `object` | required |
| `url` | `string (uri)` | required |

### erasurePlan

`GET /api/links/:linkId/erase`

What erasing everyone under one private link would take, counted by table, with the pictures of the screen that would go and whose link it is. Changes nothing: ask it before `eraseViewer`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `linkId` | `string` | required |
| `viewerId` | `string \| null` | required |
| `name` | `string \| null` | required |
| `linkItself` | `boolean` | required |
| `staying` | `integer` | required |
| `rows` | `{ [key]: integer }` | required |
| `files` | `integer` | required |

### personErasurePlan

`GET /api/links/:linkId/people/:viewerId/erase`

The same for one person under the link: someone it was passed on to, or the person it was made for, whose erasure takes the link’s own name and email too. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`, `viewerId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `linkId` | `string` | required |
| `viewerId` | `string \| null` | required |
| `name` | `string \| null` | required |
| `linkItself` | `boolean` | required |
| `staying` | `integer` | required |
| `rows` | `{ [key]: integer }` | required |
| `files` | `integer` | required |

### eraseViewer

`POST /api/links/:linkId/erase`

Erases one viewer’s data: everyone under the link, or the one person `viewerId` names. Their visits, the moments of each, comments with their threads and pictures, answers, reactions, claims, meetings and your notes are deleted, and the emails about their meetings keep nothing of the address or the words. Erasing the whole link, or the person it was made for, takes the link’s name and email and stops it opening the room. Cannot be undone. Recorded in the project’s history, naming no one.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `viewerId` | `string` | optional · 1–100 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `linkId` | `string` | required |
| `viewerId` | `string \| null` | required |
| `name` | `string \| null` | required |
| `linkItself` | `boolean` | required |
| `staying` | `integer` | required |
| `rows` | `{ [key]: integer }` | required |
| `files` | `integer` | required |

### listVisits

`GET /api/projects/:projectId/visits`

Every visit to the project’s room, with the seconds spent on each app and page. A preview records none. Pro and up: on Free it is refused with `402`, as each viewer’s journey is, and total views are on the analytics endpoints. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string \| null` | required |
| `viewerName` | `string \| null` | required |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `startedAt` | `string (date-time)` | required |
| `endedAt` | `string (date-time) \| null` | required |
| `time` | `{ [key]: integer }` | required |
| `entered` | `"declare" \| "password" \| "email" \| "door" \| null` | optional |

### listResponses

`GET /api/projects/:projectId/responses`

Every answer viewers gave to “What happens next”, with the detail they added. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `step` | `"meeting" \| "yes" \| "later" \| "colleague" \| "question" \| "no"` | required |
| `detail` | `{ [key]: any } \| null` | required |
| `createdAt` | `string (date-time)` | required |

### listComments

`GET /api/projects/:projectId/comments`

Every comment viewers left in the project’s room, with the app and screen it was pinned to and whether it is resolved. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string \| null` | required |
| `viewerName` | `string \| null` | required |
| `appId` | `string \| null` | required |
| `screen` | `string \| null` | required |
| `body` | `string` | required |
| `resolvedAt` | `string (date-time) \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `position` | `object \| null` | required |
| `area` | `object \| null` | required |
| `device` | `"phone" \| "tablet" \| "laptop" \| "screen" \| "none" \| null` | required |
| `hasScreenshot` | `boolean` | required |

### pipeline

`GET /api/pipeline`

Every viewer link across every project in the workspace, with its stage: `sent`, `opened`, `engaged`, `yes`, `later` or `no`. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |

### addPage

`POST /api/projects/:projectId/pages`

Adds a Markdown or HTML page to the project’s room, which every viewer sees at once. A page with the title of one the room already has replaces that page’s content.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `title` | `string` | required · 1–80 characters |
| `kind` | `"markdown" \| "html"` | required |
| `content` | `string` | required · at most 2000000 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `title` | `string` | required |
| `kind` | `"markdown" \| "html"` | required |

### listWorkspaces

`GET /api/workspaces`

Every workspace you belong to: your own first, then each team, with your role in each (`owner` or `member`), which one this session is working in (`active`), and the brand its plan shows (`brand`: its name and whether it has a logo, read from `GET /api/workspaces/:workspaceId/logo`; `null` for none). Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `name` | `string` | required |
| `kind` | `"personal" \| "team"` | required |
| `role` | `"owner" \| "member"` | required |
| `active` | `boolean` | required |
| `brand` | `object \| null` | optional |

### projectWorkspace

`GET /api/project-workspace/:slug`

Which of your workspaces holds the live project at this address (`workspaceId`, its `name` and `kind`, and `active` when this session is working in it already), for a link made in another workspace than the one this session is working in. Only your own workspaces are asked: a project in a workspace you are not in is the same `404` as an address with no project. Changes nothing; moving the session there is Better Auth’s set-active, as the app’s switcher does.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `slug`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `workspaceId` | `string` | required · not empty |
| `name` | `string` | required |
| `kind` | `"personal" \| "team"` | required |
| `active` | `boolean` | required |

### createTeam

`POST /api/workspaces`

Makes a team with the name given, with you as its owner, and answers it. A new team has no plan, so it holds no projects and nobody else until it has Team or Enterprise; you may have one such team at a time (`422`, `reason: unlicensed`). Your own workspace is unchanged.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–80 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `name` | `string` | required |
| `kind` | `"personal" \| "team"` | required |
| `role` | `"owner" \| "member"` | required |
| `active` | `boolean` | required |
| `brand` | `object \| null` | optional |

### listMembers

`GET /api/workspaces/:workspaceId/members`

Everyone in a workspace you belong to, owners first, each with their name, email, picture, role and when they joined; `you` marks you. Your own workspace has only you. Changes nothing; another workspace is a `404`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `displayName` | `string` | required |
| `email` | `string` | required |
| `image` | `string \| null` | required |
| `role` | `"owner" \| "member"` | required |
| `joinedAt` | `string (date-time)` | required |
| `you` | `boolean` | required |

### setMemberRole

`POST /api/workspaces/:workspaceId/members/:userId/role`

Makes someone in a team an owner or a member. An owner’s to do (`403`, `reason: permission`, for a member), and refused (`422`, `reason: team`) when it would leave the team with no owner. Answers the team’s people.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`, `userId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `role` | `"owner" \| "member"` | required |

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `displayName` | `string` | required |
| `email` | `string` | required |
| `image` | `string \| null` | required |
| `role` | `"owner" \| "member"` | required |
| `joinedAt` | `string (date-time)` | required |
| `you` | `boolean` | required |

### removeMember

`POST /api/workspaces/:workspaceId/members/:userId/remove`

Takes someone out of a team at once: from their next request they reach none of it. An owner’s to do; never yourself, which is `leaveTeam`. Answers the team’s people.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`, `userId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `displayName` | `string` | required |
| `email` | `string` | required |
| `image` | `string \| null` | required |
| `role` | `"owner" \| "member"` | required |
| `joinedAt` | `string (date-time)` | required |
| `you` | `boolean` | required |

### leaveTeam

`POST /api/workspaces/:workspaceId/leave`

Takes you out of a team. An owner leaves only while another owner stays (`422`, `reason: team`), and your own workspace is never left.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `left` | `true` | required |

### renameWorkspace

`POST /api/workspaces/:workspaceId/name`

Renames a team, or your own workspace. An owner’s to do. Your own workspace’s name is what a room shows its viewers for a link made before display names.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–80 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `name` | `string` | required |
| `kind` | `"personal" \| "team"` | required |
| `role` | `"owner" \| "member"` | required |
| `active` | `boolean` | required |
| `brand` | `object \| null` | optional |

### listInvitations

`GET /api/workspaces/:workspaceId/invitations`

A team’s invitations still waiting and not expired, each with its email, who made it and when it expires. An owner’s to see. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `email` | `string` | required |
| `role` | `"owner" \| "member"` | required |
| `invitedBy` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `expiresAt` | `string (date-time)` | required |

### createInvitation

`POST /api/workspaces/:workspaceId/invitations`

Invites one email into a team and answers the invitation with `url`, the link to send: nothing is emailed. Only someone signed in with that email, verified as theirs, can use the link, once, within 7 days. An owner’s to do; a waiting invitation holds a seat, so a team at its plan’s seats is refused (`422`, `reason: team`), and so is someone in the team already or invited already.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `email` | `string (email)` | required · at most 254 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `invitation` | `object` | required |
| `url` | `string (uri)` | required |

### revokeInvitation

`POST /api/workspaces/:workspaceId/invitations/:invitationId/revoke`

Revokes an invitation still waiting: its link stops working at once. An owner’s to do. Answers the invitations still waiting.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`, `invitationId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `email` | `string` | required |
| `role` | `"owner" \| "member"` | required |
| `invitedBy` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `expiresAt` | `string (date-time)` | required |

### viewInvitation

`GET /api/invitations/:invitationId`

An invitation, told only to the person signed in with the email it is for: the team’s name and who invited them. A used, revoked or expired invitation, or anyone else’s, is a `404`. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `invitationId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `workspaceId` | `string` | required · not empty |
| `workspaceName` | `string` | required |
| `invitedBy` | `string` | required |
| `expiresAt` | `string (date-time)` | required |

### acceptInvitation

`POST /api/invitations/:invitationId/accept`

Joins the team the invitation is for, as a member, and answers the team. Only the invited person, once, while a seat is free (`422`, `reason: team`, when none is). The joining is written in the team’s record.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `invitationId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `name` | `string` | required |
| `kind` | `"personal" \| "team"` | required |
| `role` | `"owner" \| "member"` | required |
| `active` | `boolean` | required |
| `brand` | `object \| null` | optional |

### deleteTeam

`POST /api/workspaces/:workspaceId/delete`

Deletes a team, with its name typed again as `confirm`: its name, brand, people and invitations. An owner’s to do, and only once it holds no live project and its plan is cancelled (`422`, `reason: team`). Everyone in it keeps their own workspace.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `workspaceId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `confirm` | `string` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `deleted` | `true` | required |

### projectHistory

`GET /api/projects/:projectId/history`

Every pause, change of note and resume on the project, and every link copied again (`link.copy`) or reissued (`link.reissue`) with whose it was, newest first, with who did it while they are a member. Append-only. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `kind` | `"room.pause" \| "room.message" \| "room.resume" \| "link.copy" \| "link.reissue" \| "room.busy" \| "build.preview" \| "build.preview-end" \| "viewer.erase" \| "domain.add" \| "domain.active" \| "domain.failed" \| "domain.remove" \| "entry.password" \| "entry.password-removed" \| "entry.email" \| "entry.email-off"` | required |
| `by` | `string \| null` | required |
| `message` | `string \| null` | required |
| `viewer` | `string \| null` | required |
| `until` | `string (date-time) \| null` | required |
| `domain` | `string \| null` | required |
| `at` | `string (date-time)` | required |

### getBilling

`GET /api/billing`

Your workspace’s plan and its status, its seats, this month’s usage, the viewer-hours allowance and where it stands, and whether the workspace is suspended. Also whether paid plans are open (`paidPlans`), whether you may manage billing and see invoices, a change waiting for the period’s end, and any payment not made: its stage (`grace`, `frozen`, `free`), what is owed, and the dates it freezes, moves to Free and is written off (`lifecycle`). Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `plan` | `"free" \| "pro" \| "team" \| "organisation" \| "solo" \| "studio" \| "agency" \| "enterprise"` | required |
| `kind` | `"personal" \| "team"` | optional |
| `seats` | `object` | optional |
| `interval` | `"month" \| "year" \| null` | required |
| `status` | `"active" \| "past_due" \| "canceled"` | required |
| `currentPeriodEnd` | `string (date-time) \| null` | required |
| `usage` | `object` | required |
| `allowance` | `object` | required |
| `history` | `object` | optional |
| `suspended` | `boolean` | required |
| `paidPlans` | `"off" \| "open"` | required |
| `immersive` | `boolean` | optional |
| `canManage` | `boolean` | optional |
| `canSeeInvoices` | `boolean` | optional |
| `subscribed` | `boolean` | optional |
| `cancelAtPeriodEnd` | `boolean` | optional |
| `selected` | `object \| null` | optional |
| `grace` | `object \| null` | optional |
| `frozen` | `boolean` | optional |
| `lifecycle` | `object \| null` | optional |

### billingCheckout

`POST /api/billing/checkout`

Stripe’s hosted Checkout for a paid plan (`pro`, or `team` with `seats` from 2 to 5, by `month` or `year`): the address to send the person to. VAT is added by Stripe Tax from the billing address; a VAT number can be given. It grants nothing: the plan changes when Stripe confirms the payment. A team’s owners only, or the person in their own workspace (`403` otherwise). Refused with `422` for a plan the workspace’s kind does not hold (Team for a person, Pro for a team), for seats outside the plan’s (a sixth is Enterprise, by arrangement: contact sales), for a workspace that already pays or still owes for a plan it lost.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `plan` | `"pro" \| "team"` | required |
| `interval` | `"month" \| "year"` | required |
| `seats` | `integer` | optional · at most 1000 |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

### billingPortal

`POST /api/billing/portal`

Stripe’s customer portal for the workspace: the card, the billing address and VAT number, and cancelling at the period’s end. Plans and seats are changed with `POST /api/billing/plan`, not there. After a failed payment it opens on updating the card. Owners only; `422` until the workspace has paid for something. Open while the workspace is frozen.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

### listInvoices

`GET /api/billing/invoices`

Every invoice and receipt the workspace has had, newest first: its number, date, period, total, VAT, status, any refund, and whether it is still owed. No links: ask `POST /api/billing/invoices/{invoiceId}/link` for one. Owners only (`403` otherwise); open while the workspace is frozen. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `number` | `string \| null` | required |
| `status` | `"paid" \| "open" \| "failed" \| "void"` | required |
| `createdAt` | `string (date-time)` | required |
| `periodStart` | `string (date-time) \| null` | required |
| `periodEnd` | `string (date-time) \| null` | required |
| `subtotalPence` | `integer \| null` | required |
| `taxPence` | `integer \| null` | required |
| `totalPence` | `integer` | required |
| `refundedPence` | `integer` | required |
| `currency` | `string \| null` | required |
| `owed` | `boolean` | required |

### invoiceLink

`POST /api/billing/invoices/:invoiceId/link`

Links to one invoice, asked of Stripe each time and never kept, since they expire: its PDF, and its page on Stripe, where an open invoice is paid and a paid one’s receipt is downloaded. Owners only; another workspace’s invoice is `404`. Open while the workspace is frozen. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `invoiceId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `pdfUrl` | `string (uri) \| null` | required |
| `pageUrl` | `string (uri) \| null` | required |
| `owed` | `boolean` | required |

## Changing a project

Renaming and deleting a project, the room’s order and its pages, and answering feedback.

### renameProject

`POST /api/projects/:projectId/name`

Changes the project’s name, as the room and the app show it. The slug, and so the room’s address, stays as it is.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–80 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `slug` | `string` | required · 3–40 characters |
| `name` | `string` | required |
| `visibility` | `"private" \| "public"` | required |
| `liveBuildId` | `string \| null` | required |
| `previewBuildId` | `string \| null` | optional |
| `roomUrl` | `string (uri)` | required |
| `createdAt` | `string (date-time)` | required |

### deleteProject

`POST /api/projects/:projectId/delete`

Deletes the project. `confirm` must be the project’s slug, or it is refused as `confirm`. Its links stop opening the room, and its slug is held for 30 days.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `confirm` | `string` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `deleted` | `true` | required |

### moveProject

`POST /api/projects/:projectId/move`

Moves the project, with its builds, links, viewers, feedback, pipeline, bookings, pages, files, community card and its own domain, into another workspace you belong to (`to`). Out of a team needs one of its owners; into one, any member; a workspace you are not in is `404`. Without `commit` it is a rehearsal: `plan` says what would move, what viewers would see differently, who is told and what refuses it, and nothing changes. With `commit: true` it moves only if `plan.refusals` is empty; every link keeps opening the same room. An API token cannot reach it.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `to` | `string` | required · 1–100 characters |
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `rehearsal` | `boolean` | required |
| `moved` | `boolean` | required |
| `plan` | `object` | required |
| `detail` | `string` | required |

### getRoomSetup

`GET /api/projects/:projectId/room`

The room’s order: the apps as you ordered them (`null` for `pitch.json`’s order), the pages as the rail lists them, the files listed after them, and which controls the room offers its viewers (`controls`). Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### orderApps

`POST /api/projects/:projectId/room/apps`

Sets the order the room’s switcher lists the apps in. The apps it names come first, in its order, then any it leaves out, in `pitch.json`’s; an id the live build does not have is ignored.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `ids` | `string[]` | required · at most 100 items |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### orderPages

`POST /api/projects/:projectId/room/pages`

Sets the order the rail lists the pages in. The list must name every page of the project exactly once, or it is refused as `order`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `ids` | `string[]` | required · at most 100 items |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### removePage

`POST /api/projects/:projectId/pages/:pageId/remove`

Takes a page out of the room and deletes its content. The pages after it close ranks. It is uploaded again by the next deploy if `pitch.json` still lists it.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `pageId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### orderFiles

`POST /api/projects/:projectId/room/files`

Sets the order the rail lists the files in, after the pages. The list must name every file of the project exactly once, or it is refused as `order`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `ids` | `string[]` | required · at most 100 items |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### removeFile

`POST /api/projects/:projectId/files/:fileId/remove`

Takes a file out of the room and deletes it. The files after it close ranks. A file is added with `PUT /api/projects/:projectId/files?title=…`: its own bytes, a PDF of up to 20 MB or a PNG, JPEG or WebP image of up to 5 MB, sent as what it is (`415` otherwise); a room holds up to 20.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `fileId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### setViewerControls

`POST /api/projects/:projectId/room/controls`

Which controls the room offers its viewers, every one named, each `true` or `false`: `frame`, `fullscreen`, `newTab`, `phone`, `scenarios`, `comments`, `reactions` and `nextSteps`. One switched off is gone from the room at once, and the room refuses it if a viewer asks for it anyway.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `controls` | `object` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `appOrder` | `string[] \| null` | required |
| `pages` | `object[]` | required |
| `files` | `object[]` | required |
| `controls` | `object` | required |

### listFeedback

`GET /api/projects/:projectId/feedback`

Every comment on the project, with your reply to it and whether it is resolved. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string \| null` | required |
| `viewerName` | `string \| null` | required |
| `appId` | `string \| null` | required |
| `screen` | `string \| null` | required |
| `body` | `string` | required |
| `resolvedAt` | `string (date-time) \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `position` | `object \| null` | required |
| `area` | `object \| null` | required |
| `device` | `"phone" \| "tablet" \| "laptop" \| "screen" \| "none" \| null` | required |
| `hasScreenshot` | `boolean` | required |
| `reply` | `string \| null` | required |
| `repliedAt` | `string (date-time) \| null` | required |
| `from` | `object \| null` | required |

### resolveComment

`POST /api/comments/:commentId/resolve`

Marks a comment resolved, or, with `false`, not resolved again.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `commentId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `resolved` | `boolean` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string \| null` | required |
| `viewerName` | `string \| null` | required |
| `appId` | `string \| null` | required |
| `screen` | `string \| null` | required |
| `body` | `string` | required |
| `resolvedAt` | `string (date-time) \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `position` | `object \| null` | required |
| `area` | `object \| null` | required |
| `device` | `"phone" \| "tablet" \| "laptop" \| "screen" \| "none" \| null` | required |
| `hasScreenshot` | `boolean` | required |
| `reply` | `string \| null` | required |
| `repliedAt` | `string (date-time) \| null` | required |
| `from` | `object \| null` | required |

### replyToComment

`POST /api/comments/:commentId/reply`

Answers a viewer’s comment; the viewer sees the answer in the room. One answer per comment: answering again replaces it.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `commentId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `body` | `string` | required · 1–2000 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string \| null` | required |
| `viewerName` | `string \| null` | required |
| `appId` | `string \| null` | required |
| `screen` | `string \| null` | required |
| `body` | `string` | required |
| `resolvedAt` | `string (date-time) \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `position` | `object \| null` | required |
| `area` | `object \| null` | required |
| `device` | `"phone" \| "tablet" \| "laptop" \| "screen" \| "none" \| null` | required |
| `hasScreenshot` | `boolean` | required |
| `reply` | `string \| null` | required |
| `repliedAt` | `string (date-time) \| null` | required |
| `from` | `object \| null` | required |

## Pausing a room

Closing every link to a project’s room for now, with a note to viewers, opening it again, and the project’s history of both.

### getRoomPause

`GET /api/projects/:projectId/pause`

Where the room stands: your pause (when, by whom, and the note to viewers), any pause of the platform’s (`over-limit`, `suspended`, `takedown`), and what a viewer with a working link meets now: `room`, `paused` or `unavailable`. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `owner` | `object \| null` | required |
| `system` | `"over-limit" \| "suspended" \| "takedown" \| null` | required |
| `viewers` | `"room" \| "paused" \| "unavailable"` | required |

### pauseRoom

`POST /api/projects/:projectId/pause`

Pauses the room: every working link shows a page saying who paused it, with `message` under it (at most 280 characters, or `null` for none), and no demo starts. Links, builds and pages are untouched, and deploys and new links still work. Called on a paused room, it changes the note. Recorded in the project’s history.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `message` | `string \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `owner` | `object \| null` | required |
| `system` | `"over-limit" \| "suspended" \| "takedown" \| null` | required |
| `viewers` | `"room" \| "paused" \| "unavailable"` | required |

### resumeRoom

`POST /api/projects/:projectId/resume`

Lifts your pause, so the same links open the room again. A pause of the platform’s stays, and the reply says so. Refused as `taken` when the room is not paused. Recorded in the project’s history.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `owner` | `object \| null` | required |
| `system` | `"over-limit" \| "suspended" \| "takedown" \| null` | required |
| `viewers` | `"room" \| "paused" \| "unavailable"` | required |

### projectHistory

`GET /api/projects/:projectId/history`

Every pause, change of note and resume on the project, and every link copied again (`link.copy`) or reissued (`link.reissue`) with whose it was, newest first, with who did it while they are a member. Append-only. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `kind` | `"room.pause" \| "room.message" \| "room.resume" \| "link.copy" \| "link.reissue" \| "room.busy" \| "build.preview" \| "build.preview-end" \| "viewer.erase" \| "domain.add" \| "domain.active" \| "domain.failed" \| "domain.remove" \| "entry.password" \| "entry.password-removed" \| "entry.email" \| "entry.email-off"` | required |
| `by` | `string \| null` | required |
| `message` | `string \| null` | required |
| `viewer` | `string \| null` | required |
| `until` | `string (date-time) \| null` | required |
| `domain` | `string \| null` | required |
| `at` | `string (date-time)` | required |

## The tour

The live build’s story, step by step, beside what its deploy reported of rehearsing each step.

### getTour

`GET /api/projects/:projectId/tour`

The live build’s story, step by step: each step’s app, its calls, and how its rehearsal went (`passed`, `failed`, `nothing-to-run` or `not-reported`), with what the demo last said. `build` is `null` when nothing is live. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `build` | `object \| null` | required |
| `steps` | `object[]` | required |
| `reported` | `boolean` | required |

## Analytics

Build history, each viewer’s journey through the room, and analytics over a range of days.

### buildHistory

`GET /api/projects/:projectId/builds/history`

Every build of the project, newest first, with who deployed it and each time it was made live, so the app can show what was live when. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `projectId` | `string` | required · not empty |
| `kind` | `"container" \| "static"` | required |
| `manifest` | `object` | required |
| `sizeBytes` | `integer` | required |
| `note` | `string \| null` | required |
| `live` | `boolean` | required |
| `preview` | `boolean` | optional |
| `createdAt` | `string (date-time)` | required |
| `room` | `"standard" \| "immersive"` | optional |
| `deployedBy` | `object \| null` | required |
| `releases` | `object[]` | required |

### journey

`GET /api/links/:linkId/journey`

The journey of the person a link was made for: their visits in order, what they opened, ran, said and chose, where they stopped, and how far they took the tour, with everyone who opened the link. Anyone it was passed on to has a journey of their own (`viewerJourney`), and none of it is in this one. Refused with `402` on a plan without analytics in full. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `person` | `object` | optional |
| `link` | `object` | required |
| `people` | `object[]` | required |
| `sessions` | `object[]` | required |
| `outside` | `object[]` | required |
| `tour` | `object \| null` | required |
| `windowStart` | `string (date-time) \| null` | optional |

### viewerJourney

`GET /api/viewers/:viewerId/journey`

The journey of someone a link was passed on to, who said who they were: their own visits, moments and answers alone, with the name the link was made for. Another workspace’s person is a `404`. Refused with `402` on a plan without analytics in full. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `person` | `object` | optional |
| `link` | `object` | required |
| `people` | `object[]` | required |
| `sessions` | `object[]` | required |
| `outside` | `object[]` | required |
| `tour` | `object \| null` | required |
| `windowStart` | `string (date-time) \| null` | optional |

### projectAnalytics

`GET /api/projects/:projectId/analytics/:from/:to`

One project’s analytics over a range of UTC days, written `YYYY-MM-DD`, both ends included, at most 366 days. In full on a plan with it; total views only on one without. A range that is not days, or ends before it starts, is refused as `range`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `from`, `to`

**Body:** none

**Reply:** `object`

### workspaceAnalytics

`GET /api/analytics/:from/:to`

The same as `projectAnalytics`, across every project in the workspace, with the split by project.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `from`, `to`

**Body:** none

**Reply:** `object`

### projectEngagement

`GET /api/projects/:projectId/engagement`

Every viewer on the project — the person each link was made for, and each person a link was passed on to, as a viewer of their own — hottest first by what they did (most recently seen, then return visits, people brought in, comments and questions, time inside), with that evidence in words; the summary (shared with, opened, average time inside, ready to talk, comments waiting for a reply) and the funnel from shared to ready. From the plan’s history window on. Total views only on a plan without analytics in full. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

### workspaceEngagement

`GET /api/engagement`

The same as `projectEngagement`, across every project in the workspace. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

### projectAttention

`GET /api/projects/:projectId/attention/:from/:to`

Seconds on each app and page of the room per UTC day, as a grid of sections by days, the busiest of them, and each private viewer’s own split. A visit’s seconds count on the day it began. Total views only on a plan without analytics in full. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `from`, `to`

**Body:** none

**Reply:** `object`

### projectBuildEngagement

`GET /api/projects/:projectId/builds/engagement`

What each build of one project met while it was live, newest first: visits, people, seconds inside and per person, how many came back (a visit an hour or more after their visit before, to any build), comments, and the three sections that held the most time. Each visit records the build live when it began; visits from before that was recorded (12 October 2026) are counted apart in `unrecorded`, never put in a build. From the plan’s history window on. Total views only on a plan without analytics in full. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

### projectPresence

`GET /api/projects/:projectId/presence`

Who is in the room now: each private viewer whose room page reported in the last 45 seconds and has not left, by name and with what they are on, and how many people are at the public address, never named. A count alone on a plan without analytics in full. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

### workspacePresence

`GET /api/presence`

The same as `projectPresence`, across every room in the workspace. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

### projectReactions

`GET /api/projects/:projectId/reactions`

What viewers reacted with in the project’s room (a heart, a clap, a fire): each person on a private link by name, with when each went on, and the public address’s as counts. For you and your team alone: viewers never see each other’s. On a plan without analytics in full, the public address’s counts only. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

## The pipeline

Each viewer as a card to work: placed in a stage, judged, followed up and noted. Pro and up: on Free every endpoint here is refused with `402`.

### board

`GET /api/board`

Every viewer on every project that has not been deleted, as a card — the person each link was made for, and each person a link was passed on to, with a card of their own: its stage, the stage the evidence suggests, the outcome, the follow-up, your notes and the signals behind it. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### projectBoard

`GET /api/projects/:projectId/board`

One project’s links, as cards. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### placeLink

`POST /api/links/:linkId/stage`

Places a viewer in a stage by hand, over what the evidence says; the evidence’s stage is still offered as a suggestion. `null` hands them back to the evidence.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no" \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### judgeLink

`POST /api/links/:linkId/outcome`

Marks the deal `won`, `lost` or `later`. `null` clears it.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### followUp

`POST /api/links/:linkId/follow-up`

Sets the day to follow this viewer up, and a line on what about. Both `null` clears it. Nothing is sent to anyone.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `on` | `string \| null` | required |
| `note` | `string \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### listNotes

`GET /api/links/:linkId/notes`

Your workspace’s notes on one viewer, newest first. They are never shown in the room. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string` | required · not empty |
| `body` | `string` | required |
| `by` | `string \| null` | required |
| `byImage` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |

### addNote

`POST /api/links/:linkId/notes`

Adds a note on one viewer, and returns all of their notes. Notes are never shown in the room.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `body` | `string` | required · 1–2000 characters |

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string` | required · not empty |
| `body` | `string` | required |
| `by` | `string \| null` | required |
| `byImage` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |

### removeNote

`POST /api/notes/:noteId/remove`

Removes one note, and returns the remaining notes on the same viewer.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `noteId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string` | required · not empty |
| `body` | `string` | required |
| `by` | `string \| null` | required |
| `byImage` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |

### placeViewer

`POST /api/viewers/:viewerId/stage`

The same as `placeLink`, for someone a link was passed on to: their card is their own, and placing them never moves the person the link was made for.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no" \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### judgeViewer

`POST /api/viewers/:viewerId/outcome`

The same as `judgeLink`, for someone a link was passed on to.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### followUpViewer

`POST /api/viewers/:viewerId/follow-up`

The same as `followUp`, for someone a link was passed on to. Nothing is sent to anyone.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `on` | `string \| null` | required |
| `note` | `string \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `viewerName` | `string` | required |
| `viewerEmail` | `string (email) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `recoverable` | `boolean` | optional |
| `emailedAt` | `string (date-time) \| null` | optional |
| `viewerId` | `string \| null` | optional |
| `origin` | `"named" \| "forwarded"` | optional |
| `via` | `string \| null` | optional |
| `linkId` | `string` | optional · not empty |
| `projectId` | `string` | required · not empty |
| `projectName` | `string` | required |
| `suggested` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `placed` | `boolean` | required |
| `outcome` | `"won" \| "lost" \| "later" \| null` | required |
| `followUp` | `object` | required |
| `notes` | `integer` | required |
| `signals` | `object` | required |
| `forwarded` | `object[]` | required |
| `claims` | `integer` | required |

### listViewerNotes

`GET /api/viewers/:viewerId/notes`

Your workspace’s notes on someone a link was passed on to, newest first. Never shown in the room. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string` | required · not empty |
| `body` | `string` | required |
| `by` | `string \| null` | required |
| `byImage` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |

### addViewerNote

`POST /api/viewers/:viewerId/notes`

Adds a note on someone a link was passed on to, and returns all of their notes.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `body` | `string` | required · 1–2000 characters |

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string` | required · not empty |
| `body` | `string` | required |
| `by` | `string \| null` | required |
| `byImage` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |

### followUpEvidence

`GET /api/links/:linkId/follow-up/evidence`

Exactly what the person a link was made for did, to write their follow-up from: each visit (when, how long, where the time went, what they opened and ran), how far the tour took them, their comments in their own words, their answers, the evidence in words, and your notes on them. Theirs alone, from the plan’s history window on. Refused with `402` on a plan without analytics in full or the pipeline. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `viewer` | `object` | required |
| `project` | `object` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `evidence` | `string[]` | required |
| `visits` | `object[]` | required |
| `tour` | `object \| null` | required |
| `comments` | `object[]` | required |
| `answers` | `object[]` | required |
| `notes` | `object[]` | required |
| `windowStart` | `string (date-time) \| null` | required |

### viewerFollowUpEvidence

`GET /api/viewers/:viewerId/follow-up/evidence`

The same as `followUpEvidence`, for someone a link was passed on to: their own visits, comments and answers, and your notes on them alone.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `viewer` | `object` | required |
| `project` | `object` | required |
| `stage` | `"sent" \| "opened" \| "engaged" \| "yes" \| "later" \| "no"` | required |
| `evidence` | `string[]` | required |
| `visits` | `object[]` | required |
| `tour` | `object \| null` | required |
| `comments` | `object[]` | required |
| `answers` | `object[]` | required |
| `notes` | `object[]` | required |
| `windowStart` | `string (date-time) \| null` | required |

## Feedback

One comment a viewer left, in full.

### getFeedback

`GET /api/comments/:commentId`

One comment in full: where on the stage it was pinned, the app’s name, whether a screenshot came with it, your reply, and the viewer who left it with their stage. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `commentId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `linkId` | `string \| null` | required |
| `viewerName` | `string \| null` | required |
| `appId` | `string \| null` | required |
| `screen` | `string \| null` | required |
| `body` | `string` | required |
| `resolvedAt` | `string (date-time) \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `position` | `object \| null` | required |
| `area` | `object \| null` | required |
| `device` | `"phone" \| "tablet" \| "laptop" \| "screen" \| "none" \| null` | required |
| `hasScreenshot` | `boolean` | required |
| `reply` | `string \| null` | required |
| `repliedAt` | `string (date-time) \| null` | required |
| `from` | `object \| null` | required |
| `projectId` | `string` | required · not empty |
| `appName` | `string \| null` | required |
| `screenshot` | `object \| null` | required |
| `screenshotNote` | `"removed" \| "no-answer" \| "timeout" \| "blocked" \| "tainted" \| "too-large" \| "failed" \| null` | required |
| `viewer` | `object \| null` | required |
| `thread` | `object[]` | required |

## Room setup

The next steps a room offers, the workspace’s brand, and your own community profile.

### getNextSteps

`GET /api/projects/:projectId/next-steps`

The next steps the project’s room offers at the end of a visit, as you set them, whether the plan lets you choose, and what the room offers now. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `steps` | `object[]` | required · at most 6 items |
| `removed` | `object[]` | required |
| `planAllows` | `boolean` | required |
| `offered` | `"meeting" \| "yes" \| "later" \| "colleague" \| "question" \| "no"[]` | required |

### setNextSteps

`POST /api/projects/:projectId/next-steps`

Sets which next steps the room offers, in what order and in what words. A step left out of `steps` is deleted: never offered, its words kept in `removed`; sending it again adds it back. On a plan that cannot choose, the setting is kept, and the room offers only a question.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `steps` | `object[]` | required · at most 6 items |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `steps` | `object[]` | required · at most 6 items |
| `removed` | `object[]` | required |
| `planAllows` | `boolean` | required |
| `offered` | `"meeting" \| "yes" \| "later" \| "colleague" \| "question" \| "no"[]` | required |

### getBrand

`GET /api/brand`

Your workspace’s brand: its name, accent colour and logo, and whether the plan shows it in the room. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string \| null` | required |
| `accent` | `string \| null` | required |
| `logo` | `object \| null` | required |
| `workspaceName` | `string` | required |
| `planAllows` | `boolean` | required |
| `logoAllows` | `boolean` | required |
| `problems` | `object[]` | optional |

### setBrand

`POST /api/brand`

Sets the brand’s name and accent colour (`#rrggbb`); `null` clears either. On a plan without its own branding, rooms carry “Made with Roomi” instead. An accent a viewer could not read in the room is refused with `400`, `reason: contrast`, and `problems` saying each pair that fails and a shade that would pass. The logo is uploaded with `PUT /api/brand/logo`: a PNG, JPEG or WebP image of up to 256 KB, from 16 × 16 to 2048 × 2048 pixels, and no more than 8 times as wide as it is tall.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string \| null` | required |
| `accent` | `string \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string \| null` | required |
| `accent` | `string \| null` | required |
| `logo` | `object \| null` | required |
| `workspaceName` | `string` | required |
| `planAllows` | `boolean` | required |
| `logoAllows` | `boolean` | required |
| `problems` | `object[]` | optional |

### removeLogo

`POST /api/brand/logo/remove`

Removes the brand’s logo.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string \| null` | required |
| `accent` | `string \| null` | required |
| `logo` | `object \| null` | required |
| `workspaceName` | `string` | required |
| `planAllows` | `boolean` | required |
| `logoAllows` | `boolean` | required |
| `problems` | `object[]` | optional |

### getTheme

`GET /api/brand/theme`

Your workspace’s room theme: its tokens as saved (`null` for none), whether the plan shows it, the first plan that does, every colour and value the room draws for it with your accent, and anything in it a viewer could not read now. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `theme` | `object \| null` | required |
| `planAllows` | `boolean` | required |
| `shownOn` | `string \| null` | required |
| `effective` | `{ [key]: string }` | required |
| `problems` | `object[]` | required |
| `fellBack` | `string[]` | required |

### setTheme

`POST /api/brand/theme`

Saves the room theme whole: a token left out is the room’s own. Colours are `#rrggbb`; `radius` is `square`, `soft` or `round`; `font` is `system`, `serif` or `rounded`. A theme a viewer could not read is refused with `400`, `reason: contrast`, and its `problems`. Kept whatever the plan, and shown on a plan that includes it.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `theme` | `object` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `theme` | `object \| null` | required |
| `planAllows` | `boolean` | required |
| `shownOn` | `string \| null` | required |
| `effective` | `{ [key]: string }` | required |
| `problems` | `object[]` | required |
| `fellBack` | `string[]` | required |

### resetTheme

`POST /api/brand/theme/reset`

Removes the room theme: rooms are drawn in the room’s own look again.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `theme` | `object \| null` | required |
| `planAllows` | `boolean` | required |
| `shownOn` | `string \| null` | required |
| `effective` | `{ [key]: string }` | required |
| `problems` | `object[]` | required |
| `fellBack` | `string[]` | required |

### checkTheme

`POST /api/brand/theme/check`

Checks a room theme, with another accent if you give one, and says what the room would draw and what would be refused. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `theme` | `object` | required |
| `accent` | `string \| null` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `problems` | `object[]` | required |
| `effective` | `{ [key]: string }` | required |

### listThemePresets

`GET /api/brand/theme/presets`

The room theme presets: the built-in ones every workspace has (ids starting `builtin:`), each passing every contrast check, then your workspace’s own, by name. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `presets` | `object[]` | required |

### saveThemePreset

`POST /api/brand/theme/presets`

Keeps a room theme under a `name` (up to 60 characters, unique in the workspace whatever its case): `409` when it is taken. A theme a viewer could not read is refused with `400`, `reason: contrast`, and its `problems`. A workspace keeps up to 50.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–60 characters |
| `theme` | `object` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required |
| `name` | `string` | required |
| `theme` | `object` | required |
| `builtIn` | `boolean` | required |

### renameThemePreset

`POST /api/brand/theme/presets/:presetId/rename`

Gives one of your workspace’s presets a new `name`. A built-in one keeps its own.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `presetId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–60 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required |
| `name` | `string` | required |
| `theme` | `object` | required |
| `builtIn` | `boolean` | required |

### deleteThemePreset

`POST /api/brand/theme/presets/:presetId/delete`

Deletes one of your workspace’s presets. The room theme is not touched.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `presetId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `presets` | `object[]` | required |

### applyThemePreset

`POST /api/brand/theme/presets/:presetId/apply`

Saves a preset as the room theme, checked as `POST /api/brand/theme` checks one. A preset another workspace kept is `404`, as an unknown id is.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `presetId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `theme` | `object \| null` | required |
| `planAllows` | `boolean` | required |
| `shownOn` | `string \| null` | required |
| `effective` | `{ [key]: string }` | required |
| `problems` | `object[]` | required |
| `fellBack` | `string[]` | required |

### getProfile

`GET /api/me/profile`

Your own community handle and bio. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `handle` | `string \| null` | required |
| `bio` | `string \| null` | required |

### setProfile

`POST /api/me/profile`

Sets your community handle and bio. The handle follows a project address’s rules and is unique among people: refused as `format`, `reserved`, `impersonation`, `banned` or `taken`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `handle` | `string` | required · 3–40 characters |
| `bio` | `string \| null` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `handle` | `string \| null` | required |
| `bio` | `string \| null` | required |

## The community

A project’s community card, listing and unlisting it, the room’s access rule, and the one-time passes into a room.

### getCard

`GET /api/projects/:projectId/card`

The project’s community card: its title, line and cover, where its listing stands (`draft`, `listed`, `blocked` with what a check found, `pulled` with Roomi's comment, or `pending` while it waits for review), whether a new cover is still held back, whether a review can be asked for, the public address it would have, and whether suggested wording is available. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### saveCard

`POST /api/projects/:projectId/card`

Saves the card’s title and line. A listed card’s new words are checked first: it stays listed if they pass, and is blocked (off the community) if a check fails. At most 10 such edits a day; past that, `429`. Any other card keeps its state. The cover is uploaded with `PUT /api/projects/:projectId/card/cover`: a PNG, JPEG or WebP image of up to 1 MB, once the card exists; a new cover is held back from the community until its own check passes.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `title` | `string` | required · 1–60 characters |
| `line` | `string` | required · 1–140 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### removeCover

`POST /api/projects/:projectId/card/cover/remove`

Removes the card’s cover.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### checkBuildCover

`POST /api/projects/:projectId/card/cover/build/check`

Reads an image in the project’s live build, by its `path` from the build’s root, as the card’s cover would take it, and returns its `type` and size in `bytes`. The type is read from the file’s bytes, never its name: a PNG, JPEG or WebP image, at most 1 MB, or it is refused as `file`. A container build is never unpacked, so its files are refused too. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `path` | `string` | required · 1–255 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `path` | `string` | required |
| `type` | `"image/png" \| "image/jpeg" \| "image/webp"` | required |
| `bytes` | `integer` | required |

### coverFromBuild

`POST /api/projects/:projectId/card/cover/build`

Makes an image in the project’s live build the card’s cover, checked as `checkBuildCover` checks it, and copied on the platform: nothing is uploaded, and the cover is stored and served from the card’s row like an uploaded one. Needs a saved card. Held back from the community until its own check passes, as with an upload.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `path` | `string` | required · 1–255 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### listProject

`POST /api/projects/:projectId/card/list`

Lists the project on the community: runs the pre-flight scan, which warns and never blocks, and Roomi's checks. If they pass it is `listed` at once; if one fails it is `blocked`, with the part and the reason. After Roomi took it off before, it waits for review (`pending`). Refused as `unfinished` without a card or without a live build; at most 3 a day for a workspace, `429` past that.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### rehearseListing

`GET /api/projects/:projectId/card/listing`

What asking to list would do now — `listed`, `blocked` with its findings, `pending`, `already` or `refused` — and why, with the pre-flight warnings. Runs the checks without the content classifier, and writes and counts nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `outcome` | `"listed" \| "blocked" \| "pending" \| "already" \| "refused"` | required |
| `findings` | `object[]` | required |
| `warnings` | `object[]` | required |
| `said` | `string[]` | required |

### appealListing

`POST /api/projects/:projectId/card/appeal`

Asks Roomi to review a block or a decision to take the listing off, in your own words (10 to 1,000 characters). One open at a time, at most 3 a workspace in 30 days: `409` while one is open, `429` past the limit. If it is upheld, exactly this card and build are listed.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `message` | `string` | required · 10–1000 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### listNotices

`GET /api/notices`

Your own notices in this workspace, newest first, the last fifty: a listing taken off, a project taken down, a review decided. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `kind` | `"listing.blocked" \| "listing.pulled" \| "listing.unlisted" \| "listing.takedown" \| "appeal.upheld" \| "appeal.denied" \| "plans.open" \| "viewer.opened" \| "viewer.returned" \| "viewer.wrote" \| "viewer.yes" \| "meeting.booked" \| "meeting.cancelled" \| "feedback.replied" \| "summary.weekly" \| "project.moved" \| "plan.granted" \| "plan.grant-ending" \| "plan.grant-ended"` | required |
| `title` | `string` | required |
| `body` | `string` | required |
| `href` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `readAt` | `string (date-time) \| null` | required |

### readNotices

`POST /api/notices/read`

Marks your own notices read: the `ids` given, or all of them. Says how many changed.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `ids` | `string[]` | optional · at most 50 items |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `read` | `integer` | required |

### scanCard

`POST /api/projects/:projectId/card/scan`

Runs the pre-flight scan on the project with the `title` and `line` given, as asking to list would, and returns its `warnings`. Changes nothing: the card is not saved and nothing is listed. The Claude connector’s `set_community_card` and `request_listing` show it before you agree.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `title` | `string` | required · 1–60 characters |
| `line` | `string` | required · 1–140 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `warnings` | `object[]` | required |

### unlistProject

`POST /api/projects/:projectId/card/unlist`

Takes the project off the community at once; its public address stops answering. The card is kept as a draft.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `projectId` | `string` | required · not empty |
| `title` | `string` | required |
| `line` | `string` | required |
| `cover` | `object \| null` | required |
| `status` | `"draft" \| "listed" \| "blocked" \| "pulled" \| "pending"` | required |
| `rejectReason` | `string \| null` | required |
| `submittedAt` | `string (date-time) \| null` | required |
| `reviewedAt` | `string (date-time) \| null` | required |
| `warnings` | `object[]` | required |
| `blocked` | `object[]` | required |
| `coverPending` | `boolean` | required |
| `hidden` | `boolean` | required |
| `appealable` | `boolean` | required |
| `appeal` | `object \| null` | required |
| `publicUrl` | `string (uri)` | required |
| `suggest` | `boolean` | optional |
| `updatedAt` | `string (date-time) \| null` | required |

### previewPass

`POST /api/projects/:projectId/preview`

A one-time address that opens the room exactly as a viewer sees it, marked as a preview, recording nothing. For a member of the project’s workspace; it lives 120 seconds and is spent on arrival.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

### getAccess

`GET /api/projects/:projectId/access`

Whether the project’s private links ask for an email before the room shows anything, and whether the plan has private links at all. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `requireEmail` | `boolean` | required |
| `privateLinks` | `boolean` | required |
| `immersive` | `object` | optional |

### setAccess

`POST /api/projects/:projectId/access`

Sets whether the project’s private links ask the viewer for an email before the room shows anything. Nothing is sent to the email, and it is not verified.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `requireEmail` | `boolean` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `requireEmail` | `boolean` | required |
| `privateLinks` | `boolean` | required |
| `immersive` | `object` | optional |

### communityPass

`POST /api/community/pass`

A one-time address back into a listed project’s room, signed in, to comment or react. Any signed-in person may ask, for any listed project; the room learns their public face and nothing else. A project that is not listed is `404`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `slug` | `string` | required · 1–63 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

## Arranging projects

Your workspace’s own order and groups of projects, as the app’s side bar and Projects page draw them, and where each project stands on the community. Cosmetic: nothing here changes who can see a project.

### getArrangement

`GET /api/arrangement`

Your workspace’s groups in order, and every project once, in the order it is drawn: the ungrouped first, then each group’s. A project nobody has placed yet comes first, newest first. Each says where it stands on the community: `unlisted`, `listed`, `blocked` (a check kept it off), `pulled` (taken off) or `pending` (waiting for review). Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `groups` | `object[]` | required |
| `projects` | `object[]` | required |

### arrangeProjects

`POST /api/arrangement`

Sets the order: the ungrouped projects, then each group with its projects, groups in the order given. What is left out keeps its place after what was given. Each id at most once (`422` otherwise); a project or group not your workspace’s is `404`, and nothing moves.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `ungrouped` | `string[]` | required · at most 500 items |
| `groups` | `object[]` | required · at most 30 items |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `groups` | `object[]` | required |
| `projects` | `object[]` | required |

### createGroup

`POST /api/groups`

Adds an empty group, last. Its name is 1 to 40 characters; a workspace has at most 30 groups.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–40 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `groups` | `object[]` | required |
| `projects` | `object[]` | required |

### renameGroup

`POST /api/groups/:groupId`

Renames one group. Another workspace’s group is `404`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `groupId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–40 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `groups` | `object[]` | required |
| `projects` | `object[]` | required |

### deleteGroup

`POST /api/groups/:groupId/delete`

Deletes one group and nothing else: its projects move to the end of the ungrouped. Another workspace’s group is `404`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `groupId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `groups` | `object[]` | required |
| `projects` | `object[]` | required |

## Public

Answers anyone, signed in or not, and shows only what is listed on the community.

### profile

`GET /api/community/people/:handle`

A publisher’s public page, by handle: their name, avatar and bio, and their projects listed on the community. A handle nobody has is `404`.

Open to anyone, signed in or not.

**Path parameters:** `handle`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `handle` | `string` | required |
| `name` | `string` | required |
| `bio` | `string \| null` | required |
| `image` | `string (uri) \| null` | required |
| `projects` | `object[]` | required |

### listings

`GET /api/community/listings`

Every project listed on the community, newest listing first: each card’s title and line, its public address, and whether it has a cover (at `/api/community/projects/:slug/cover`). Nothing about who built it: no name, handle, avatar or email. Cached for a minute; getroomi.com may read it from a browser.

Open to anyone, signed in or not.

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `slug` | `string` | required |
| `title` | `string` | required |
| `line` | `string` | required |
| `url` | `string (uri)` | required |
| `cover` | `boolean` | required |
| `listedAt` | `string (date-time)` | required |
| `credit` | `string \| null` | optional |
| `type` | `"static" \| "container" \| "immersive"` | optional |

## Plan and usage

The workspace’s plan, and what it has used this month.

### getBilling

`GET /api/billing`

Your workspace’s plan and its status, its seats, this month’s usage, the viewer-hours allowance and where it stands, and whether the workspace is suspended. Also whether paid plans are open (`paidPlans`), whether you may manage billing and see invoices, a change waiting for the period’s end, and any payment not made: its stage (`grace`, `frozen`, `free`), what is owed, and the dates it freezes, moves to Free and is written off (`lifecycle`). Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `plan` | `"free" \| "pro" \| "team" \| "organisation" \| "solo" \| "studio" \| "agency" \| "enterprise"` | required |
| `kind` | `"personal" \| "team"` | optional |
| `seats` | `object` | optional |
| `interval` | `"month" \| "year" \| null` | required |
| `status` | `"active" \| "past_due" \| "canceled"` | required |
| `currentPeriodEnd` | `string (date-time) \| null` | required |
| `usage` | `object` | required |
| `allowance` | `object` | required |
| `history` | `object` | optional |
| `suspended` | `boolean` | required |
| `paidPlans` | `"off" \| "open"` | required |
| `immersive` | `boolean` | optional |
| `canManage` | `boolean` | optional |
| `canSeeInvoices` | `boolean` | optional |
| `subscribed` | `boolean` | optional |
| `cancelAtPeriodEnd` | `boolean` | optional |
| `selected` | `object \| null` | optional |
| `grace` | `object \| null` | optional |
| `frozen` | `boolean` | optional |
| `lifecycle` | `object \| null` | optional |

### projectBounces

`GET /api/projects/:projectId/bounces`

How many viewers a full room turned away from the project this calendar month (UTC), counted once per session per hour. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `thisMonth` | `integer` | required |

### billingCheckout

`POST /api/billing/checkout`

Stripe’s hosted Checkout for a paid plan (`pro`, or `team` with `seats` from 2 to 5, by `month` or `year`): the address to send the person to. VAT is added by Stripe Tax from the billing address; a VAT number can be given. It grants nothing: the plan changes when Stripe confirms the payment. A team’s owners only, or the person in their own workspace (`403` otherwise). Refused with `422` for a plan the workspace’s kind does not hold (Team for a person, Pro for a team), for seats outside the plan’s (a sixth is Enterprise, by arrangement: contact sales), for a workspace that already pays or still owes for a plan it lost.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `plan` | `"pro" \| "team"` | required |
| `interval` | `"month" \| "year"` | required |
| `seats` | `integer` | optional · at most 1000 |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

### billingPortal

`POST /api/billing/portal`

Stripe’s customer portal for the workspace: the card, the billing address and VAT number, and cancelling at the period’s end. Plans and seats are changed with `POST /api/billing/plan`, not there. After a failed payment it opens on updating the card. Owners only; `422` until the workspace has paid for something. Open while the workspace is frozen.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

### billingChangePlan

`POST /api/billing/plan`

Changes a paid subscription’s billing period or a team’s seats. Without `commit: true` it is a rehearsal and changes nothing: it says whether the change is an upgrade or a downgrade, what an upgrade charges now, when a downgrade lands, which projects would pause, and why it would be refused. More seats, or a month to a year, take effect at once, invoiced with proration, and keep what it had until it is paid (`payUrl` is Stripe’s page for a payment that needs the person). Fewer seats, or a year to a month, wait for the period’s end and refund nothing; choosing what it has again drops the change. More of one and less of the other is refused (`mixed`): one at a time. Seats the team’s people do not fit, and a sixth seat, are refused. Owners only, and not while a payment is owed.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `plan` | `"pro" \| "team"` | required |
| `interval` | `"month" \| "year"` | required |
| `seats` | `integer` | optional · at most 1000 |
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `direction` | `"upgrade" \| "downgrade" \| "same" \| "mixed"` | required |
| `from` | `object` | required |
| `to` | `object` | required |
| `takesEffect` | `"now" \| "period-end"` | required |
| `at` | `string (date-time) \| null` | required |
| `amountDuePence` | `integer \| null` | required |
| `pauses` | `string[]` | required |
| `refusals` | `string[]` | required |
| `payUrl` | `string (uri) \| null` | required |
| `detail` | `string` | required |

### billingChooseFree

`POST /api/billing/free`

While a payment is owed, moves the workspace to Free now: the subscription is cancelled in Stripe, nothing is refunded, its most recently used projects keep running, and what it had is not kept. What is owed stays owed until it is paid, and no paid plan can be chosen until then. Without `commit: true` it is a rehearsal and names the projects that would pause. Owners only; open while the workspace is frozen.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `refusals` | `string[]` | required |
| `pauses` | `string[]` | required |
| `running` | `integer \| null` | required |
| `detail` | `string` | required |

### billingRestore

`POST /api/billing/restore`

After a workspace moved to Free for a payment not made, and that payment is now paid: Stripe’s Checkout for the plan it had, at the seats and billing period it had. Once paid, everything comes back, the projects that ran before first. Owners only.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `url` | `string (uri)` | required |

### listInvoices

`GET /api/billing/invoices`

Every invoice and receipt the workspace has had, newest first: its number, date, period, total, VAT, status, any refund, and whether it is still owed. No links: ask `POST /api/billing/invoices/{invoiceId}/link` for one. Owners only (`403` otherwise); open while the workspace is frozen. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `number` | `string \| null` | required |
| `status` | `"paid" \| "open" \| "failed" \| "void"` | required |
| `createdAt` | `string (date-time)` | required |
| `periodStart` | `string (date-time) \| null` | required |
| `periodEnd` | `string (date-time) \| null` | required |
| `subtotalPence` | `integer \| null` | required |
| `taxPence` | `integer \| null` | required |
| `totalPence` | `integer` | required |
| `refundedPence` | `integer` | required |
| `currency` | `string \| null` | required |
| `owed` | `boolean` | required |

### invoiceLink

`POST /api/billing/invoices/:invoiceId/link`

Links to one invoice, asked of Stripe each time and never kept, since they expire: its PDF, and its page on Stripe, where an open invoice is paid and a paid one’s receipt is downloaded. Owners only; another workspace’s invoice is `404`. Open while the workspace is frozen. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `invoiceId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `pdfUrl` | `string (uri) \| null` | required |
| `pageUrl` | `string (uri) \| null` | required |
| `owed` | `boolean` | required |

## You, and your workspace’s people

Your name and photo as the app draws you, how you sign in and where you are signed in, deleting your account, and your workspace’s people and container demos. Nothing here names anyone else to change.

### whoami

`GET /api/me/account`

Who you are, as the app draws you: your name (or your email while you have set none), your picture — your uploaded photo, else your sign-in provider’s avatar, else none — and the workspace your session is in, with your role. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `name` | `string` | required |
| `displayName` | `string` | required |
| `nameChosen` | `boolean` | optional |
| `suggestedName` | `string` | optional |
| `email` | `string` | required |
| `emailVerified` | `boolean` | required |
| `image` | `string \| null` | required |
| `photo` | `object \| null` | required |
| `providerImage` | `boolean` | required |
| `handle` | `string \| null` | required |
| `workspace` | `object` | required |
| `createdAt` | `string (date-time)` | required |

### setName

`POST /api/me/name`

Sets the name you are shown by, to you and to the people in your workspace: 1 to 80 characters.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–80 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `name` | `string` | required |
| `displayName` | `string` | required |
| `nameChosen` | `boolean` | optional |
| `suggestedName` | `string` | optional |
| `email` | `string` | required |
| `emailVerified` | `boolean` | required |
| `image` | `string \| null` | required |
| `photo` | `object \| null` | required |
| `providerImage` | `boolean` | required |
| `handle` | `string \| null` | required |
| `workspace` | `object` | required |
| `createdAt` | `string (date-time)` | required |

### removePhoto

`POST /api/me/photo/remove`

Removes your uploaded photo; you are drawn with your provider’s avatar, or your initials. A photo is uploaded with `PUT /api/me/photo`: a PNG, JPEG or WebP image of up to 2 MB and 4096 pixels a side, checked by its own bytes.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `name` | `string` | required |
| `displayName` | `string` | required |
| `nameChosen` | `boolean` | optional |
| `suggestedName` | `string` | optional |
| `email` | `string` | required |
| `emailVerified` | `boolean` | required |
| `image` | `string \| null` | required |
| `photo` | `object \| null` | required |
| `providerImage` | `boolean` | required |
| `handle` | `string \| null` | required |
| `workspace` | `object` | required |
| `createdAt` | `string (date-time)` | required |

### deletable

`GET /api/me/deletable`

Whether your account can be deleted now, and what stands in the way: a workspace you own that still holds projects or other people. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `allowed` | `boolean` | required |
| `blockers` | `object[]` | required |

### deleteAccount

`POST /api/me/delete`

Deletes your account: your sign-in methods, passkeys and sessions, your profile and photo, and every workspace you own. `confirm` must be your email. Refused with `422` while `deletable` names a workspace.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `confirm` | `string` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `deleted` | `true` | required |

### containerUsage

`GET /api/usage/containers`

Your workspace’s container demos this calendar month (UTC): runs, container-hours, starts that failed, viewers held back at the plan’s cap, and the median start. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `month` | `string` | required |
| `runs` | `integer` | required |
| `containerHours` | `number` | required |
| `failedStarts` | `integer` | required |
| `heldBack` | `integer` | required |
| `medianColdStartMs` | `integer \| null` | required |

### members

`GET /api/workspace/people`

The people in your workspace, each with the name and picture the app draws them with. Their photos are served at `GET /api/people/:userId/photo` to people in a workspace with them, and to nobody else. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `userId` | `string` | required · not empty |
| `displayName` | `string` | required |
| `image` | `string \| null` | required |

### signIns

`GET /api/me/sign-in`

How you can sign in: GitHub and Google, each set up on the platform or not and linked to you or not, how many passkeys you have, and whether emailed links are offered. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `providers` | `object[]` | required |
| `passkeys` | `integer` | required |
| `magicLinks` | `boolean` | required |

### disconnect

`POST /api/me/sign-in/:provider/disconnect`

Unlinks GitHub or Google from your account. Refused with `422` while it is your only way in: no other provider, and no passkey.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `provider`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `providers` | `object[]` | required |
| `passkeys` | `integer` | required |
| `magicLinks` | `boolean` | required |

### sessions

`GET /api/me/sessions`

Every live session of yours, newest first, with the one asking marked `current`. Each has an id to sign it out by, never the token a cookie carries. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `current` | `boolean` | required |
| `signInMethod` | `string \| null` | required |
| `userAgent` | `string \| null` | required |
| `device` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `expiresAt` | `string (date-time)` | required |

### revokeSession

`POST /api/me/sessions/:sessionId/revoke`

Signs out one of your sessions. Another person’s session is a `404`, and nothing changes.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `sessionId`

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `current` | `boolean` | required |
| `signInMethod` | `string \| null` | required |
| `userAgent` | `string \| null` | required |
| `device` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `expiresAt` | `string (date-time)` | required |

### signOutEverywhere

`POST /api/me/sessions/revoke-all`

Signs out every session of yours, the one asking included.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `signedOut` | `integer` | required |

## Your first days

The welcome letter, whether you have read it, and a note to the Roomi team from inside the app. Each answers only for the person signed in.

### myPreferences

`GET /api/me/preferences`

Your own preferences: whether you have read the welcome letter and whether the feedback tab is folded. Someone with none yet gets the defaults. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `welcomeSeenAt` | `string (date-time) \| null` | required |
| `feedbackTabFolded` | `boolean` | required |

### welcomeSeen

`POST /api/me/welcome/seen`

Marks the welcome letter as read, the first time only; calling it again changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `welcomeSeenAt` | `string (date-time) \| null` | required |
| `feedbackTabFolded` | `boolean` | required |

### foldFeedbackTab

`POST /api/me/feedback-tab`

Folds the “Help us improve” button to a small tab, or opens it out again. Yours alone.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `folded` | `boolean` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `welcomeSeenAt` | `string (date-time) \| null` | required |
| `feedbackTabFolded` | `boolean` | required |

### myOnboarding

`GET /api/me/onboarding`

Your first run: what you chose on it (on your own or with a team, the plan you want, whether you have left the set-up or hidden its checklist, and where you are in the app’s tour), and the facts it is read from, of the workspace you are signed in to: a connection from Claude or the CLI, a project, a viewer link or a listing, a visit. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `use` | `"solo" \| "team" \| null` | required |
| `planIntent` | `"free" \| "pro" \| "team" \| "organisation" \| null` | required |
| `flowLeftAt` | `string (date-time) \| null` | required |
| `checklistDismissedAt` | `string (date-time) \| null` | required |
| `tour` | `object` | required |
| `facts` | `object` | required |

### setOnboarding

`POST /api/me/onboarding`

Saves what you chose on the first run: any of `use`, `planIntent` (one of the plans’ ids; anything else is `400`), `flowLeft` and `checklistDismissed`. A field left out is kept, and the first time you left the set-up stands. Yours alone: the body cannot name a workspace.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `use` | `"solo" \| "team"` | optional |
| `planIntent` | `"free" \| "pro" \| "team" \| "organisation"` | optional |
| `flowLeft` | `true` | optional |
| `checklistDismissed` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `use` | `"solo" \| "team" \| null` | required |
| `planIntent` | `"free" \| "pro" \| "team" \| "organisation" \| null` | required |
| `flowLeftAt` | `string (date-time) \| null` | required |
| `checklistDismissedAt` | `string (date-time) \| null` | required |
| `tour` | `object` | required |
| `facts` | `object` | required |

### setTour

`POST /api/me/onboarding/tour`

Saves where you are in the app’s tour: `step`, the stop on show (one of `projects`, `room`, `links`, `activity`, `pipeline` and `claude`), and `ended`, `finished` or `skipped`. The first time you were shown it stands; a stop after an end clears the end. Yours alone, on every device; nothing about it is kept in the browser.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `step` | `"projects" \| "room" \| "links" \| "activity" \| "pipeline" \| "claude"` | optional |
| `ended` | `"finished" \| "skipped"` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `use` | `"solo" \| "team" \| null` | required |
| `planIntent` | `"free" \| "pro" \| "team" \| "organisation" \| null` | required |
| `flowLeftAt` | `string (date-time) \| null` | required |
| `checklistDismissedAt` | `string (date-time) \| null` | required |
| `tour` | `object` | required |
| `facts` | `object` | required |

### sendProductFeedback

`POST /api/product-feedback`

A note to the Roomi team, filed under you and the workspace you are signed in to, whatever the body says. Up to 2,000 characters, and a few an hour; past that, `429`. Says back only that it arrived.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `body` | `string` | required · 1–2000 characters |
| `page` | `string` | optional · at most 300 characters |
| `appVersion` | `string` | optional · at most 64 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `createdAt` | `string (date-time)` | required |

## Notifications

What you hear about, in the app and by email, and your notes to the Roomi team with our replies. Each answers only for the person signed in; the notices themselves are under The community.

### myNotificationPreferences

`GET /api/me/notifications`

What you hear about: for each kind (a viewer opens a link for the first time, comments or asks a question, says yes, a meeting booked or cancelled, a reply to your note), whether it shows in the app and whether it is emailed, as you chose it or by default. With whether the platform sends email yet, and whether your address unsubscribed. Yours alone, in every workspace. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `settings` | `object[]` | required |
| `emailOn` | `boolean` | required |
| `unsubscribed` | `boolean` | required |

### setNotificationPreference

`POST /api/me/notifications`

Turns one kind on or off on one channel, `app` or `email`, for you alone, and answers with every setting. Only the kinds listed can be set: sign-in, security, billing and listing emails are always sent, and asking for one is `400`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `kind` | `"viewer.opened" \| "viewer.returned" \| "viewer.wrote" \| "viewer.yes" \| "meeting.booked" \| "meeting.cancelled" \| "feedback.replied" \| "summary.weekly" \| "project.moved"` | required |
| `channel` | `"app" \| "email"` | required |
| `enabled` | `boolean` | required |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `settings` | `object[]` | required |
| `emailOn` | `boolean` | required |
| `unsubscribed` | `boolean` | required |

### resubscribe

`POST /api/me/notifications/resubscribe`

Turns optional email back on for your own address after you followed an unsubscribe link in one. Only an unsubscribe of yours is undone; an address that bounced stays as it is.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `settings` | `object[]` | required |
| `emailOn` | `boolean` | required |
| `unsubscribed` | `boolean` | required |

### myNotes

`GET /api/me/notes`

Your notes to the Roomi team, newest first, each with the conversation since: your answers and the team’s replies, signed by Roomi. Only your own. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `body` | `string` | required |
| `page` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `replied` | `boolean` | required |
| `messages` | `object[]` | required |

### replyOnNote

`POST /api/me/notes/:noteId/replies`

Your answer on one of your own notes, up to 2,000 characters: it joins the conversation and the team sees the note again. Someone else’s note is `404`, as one that does not exist; past a few answers an hour, `429`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `noteId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `body` | `string` | required · 1–2000 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `body` | `string` | required |
| `page` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `replied` | `boolean` | required |
| `messages` | `object[]` | required |

## Reports

Reporting a project to Roomi.

### reportProject

`POST /api/reports`

Reports a project, by its address, to Roomi, with a reason and any detail. A project that does not exist is `404`; more than 20 reports from one person in 24 hours is `429`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `slug` | `string` | required · 1–63 characters |
| `reason` | `"phishing" \| "impersonation" \| "abuse" \| "illegal" \| "spam" \| "other"` | required |
| `detail` | `string` | optional · at most 1000 characters |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |

## API tokens

Your own API tokens in the active workspace, made, listed and revoked signed in. A token cannot reach these: it cannot make or revoke tokens.

### listTokens

`GET /api/tokens`

Your API tokens in the active workspace, newest first, revoked and expired ones included. Never a token itself. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object[]`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `name` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `lastUsedAt` | `string (date-time) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |

### createToken

`POST /api/tokens`

Makes an API token with a name and, if you give one, an expiry of 1 to 365 days. `secret` is the token: in this reply once, and never again, since only its hash is kept. Refused as `tokens` when you already hold 20 live tokens in the workspace.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `name` | `string` | required · 1–60 characters |
| `expiresInDays` | `integer` | optional · 1–365 |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `token` | `object` | required |
| `secret` | `string (starts_with)` | required |

### revokeToken

`POST /api/tokens/:tokenId/revoke`

Stops one of your own tokens at once and records who did it. Another person’s token, or one already revoked, is `404`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `tokenId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `name` | `string` | required |
| `createdAt` | `string (date-time)` | required |
| `lastUsedAt` | `string (date-time) \| null` | required |
| `expiresAt` | `string (date-time) \| null` | required |
| `revokedAt` | `string (date-time) \| null` | required |

## Your own domain

A project’s room at an address of yours, on the plans that include it ([Your own domain](https://getroomi.com/docs/domains)). Signed in; an API token cannot reach these. Where custom domains are not available, the list says so and every other call answers `503` (`reason: unavailable`).

### listDomains

`GET /api/projects/:projectId/domains`

The project’s own domain, if it has one: its hostname, where it stands (`pending`, `active` or `failed`), the DNS records to create, what is wrong if anything is, and the room’s address on it once it is active. `available` is false, and nothing else is said, where custom domains are not available; `included` says whether the plan has them, and `upgrade` the plan that does when it does not. `target` is what the `CNAME` record points at. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `available` | `boolean` | required |
| `included` | `boolean` | required |
| `upgrade` | `string \| null` | required |
| `target` | `string` | required |
| `domains` | `object[]` | required |

### addDomain

`POST /api/projects/:projectId/domains`

Asks for the room at a hostname. Without `commit` it is a rehearsal: it checks the plan, the hostname and that no room has it, says what would happen in `detail` and what stands in the way in `refusals`, and changes nothing. With `commit: true` the hostname is made in Cloudflare and the records it asks for come back in `domain`; a hostname Cloudflare refuses is added as `failed`, saying why. One domain a project. Recorded in the project’s history.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `hostname` | `string` | required · 1–269 characters |
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `refusals` | `string[]` | required |
| `detail` | `string` | required |
| `domain` | `object \| null` | required |

### checkDomain

`POST /api/projects/:projectId/domains/:domainId/check`

Asks Cloudflare how the domain stands now, and asks it to check the records again if it is waiting for them. Moving to `active` or `failed` is recorded in the project’s history. Another workspace’s domain is `404`.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `domainId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | required · not empty |
| `hostname` | `string` | required |
| `status` | `"pending" \| "active" \| "failed" \| "removed"` | required |
| `records` | `object[]` | required |
| `problem` | `string \| null` | required |
| `url` | `string \| null` | required |
| `createdAt` | `string (date-time)` | required |
| `checkedAt` | `string (date-time) \| null` | required |
| `activeAt` | `string (date-time) \| null` | required |

### removeDomain

`POST /api/projects/:projectId/domains/:domainId/remove`

Stops the room answering at the domain. Without `commit` it is a rehearsal and changes nothing; with `commit: true` it is removed from Cloudflare and from the project, for good, and recorded in the project’s history. Every link keeps working at the room’s own address. Refused as `cloudflare` when Cloudflare cannot be asked, with nothing removed.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `domainId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `refusals` | `string[]` | required |
| `detail` | `string` | required |
| `domain` | `object \| null` | required |

## Screens and clicks

What viewers who said yes did inside the demo, and the settings that decide it, on Pro and above ([Screens and clicks](https://getroomi.com/docs/screens)). Signed in; an API token cannot reach these. Another workspace’s id is `404`, and a plan without it `402`. Every string the demo wrote is marked `reportedByTheDemo`. A change is a rehearsal unless the body has `commit: true`.

### getRecording

`GET /api/projects/:projectId/recording`

Whether the project logs what viewers do inside the demo, and why not when it does not: the setting, the plan, the workspace’s privacy contact, and the parts of the demo left out (`mask` and `ignore`, and those `pitch.json` names). Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `available` | `boolean` | required |
| `insight` | `boolean` | optional |
| `level` | `"off" \| "clicks"` | required |
| `chosen` | `"off" \| "clicks" \| null` | required |
| `why` | `"switched-off" \| "plan" \| "no-contact" \| "chosen-off" \| "on"` | required |
| `included` | `boolean` | required |
| `upgrade` | `string \| null` | required |
| `contact` | `string \| null` | required |
| `mask` | `string[]` | required |
| `ignore` | `string[]` | required |
| `manifestMask` | `string[]` | required |
| `changedBy` | `object \| null` | required |
| `changedAt` | `string (date-time) \| null` | required |

### setRecording

`PUT /api/projects/:projectId/recording`

Turns screens and clicks on or off for the project, and sets the parts of the demo to leave out. Without `commit` it is a rehearsal: it says what would change and what stands in the way in `refusals`, and changes nothing. Turning it on needs the workspace’s privacy contact. The setting keeps who changed it last, and when.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `level` | `"off" \| "clicks"` | optional |
| `mask` | `string[]` | optional · at most 20 items |
| `ignore` | `string[]` | optional · at most 20 items |
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `refusals` | `string[]` | required |
| `setting` | `object` | required |

### getPrivacyContact

`GET /api/workspace/privacy-contact`

The address viewers are shown for questions about their data, and who set it and when. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `available` | `boolean` | required |
| `email` | `string \| null` | required |
| `changedBy` | `object \| null` | required |
| `changedAt` | `string (date-time) \| null` | required |

### setPrivacyContact

`PUT /api/workspace/privacy-contact`

Sets that address, for every project in the workspace. Without `commit` it is a rehearsal and changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Body:** `object`

| Field | Type | |
|---|---|---|
| `email` | `string (email)` | required · at most 254 characters |
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `available` | `boolean` | required |
| `email` | `string \| null` | required |
| `changedBy` | `object \| null` | required |
| `changedAt` | `string (date-time) \| null` | required |

### linkScreens

`GET /api/links/:linkId/screens`

The visits on one link, screen by screen inside the demo: what was opened, in order and for how long, and what was clicked there. A visit with nothing logged says so, never why. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `linkId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `visits` | `object[]` | required |
| `windowStart` | `string (date-time) \| null` | required |

### viewerScreens

`GET /api/viewers/:viewerId/screens`

The same for someone the link was passed on to: their own visits, never those of the person it was made for. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `viewerId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `visits` | `object[]` | required |
| `windowStart` | `string (date-time) \| null` | required |

### projectScreens

`GET /api/projects/:projectId/screens/:build`

Every screen viewers opened in one build (its id, or `live`), with its views, time and clicks. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `build`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `build` | `object` | required |
| `builds` | `object[]` | required |
| `screens` | `object[]` | required |
| `windowStart` | `string (date-time) \| null` | required |

### projectClicks

`GET /api/projects/:projectId/clicks/:build`

What viewers clicked and which fields they used in one build, by the demo’s own labels, never what was typed. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `build`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `build` | `object` | required |
| `elements` | `object[]` | required · at most 200 items |
| `fields` | `object[]` | required |
| `windowStart` | `string (date-time) \| null` | required |

### screenHeatmap

`GET /api/projects/:projectId/heatmap/:build/:ref/:bucket`

Where viewers clicked on one screen of a build and how far down they read, at one width (`:bucket`), over a picture of the screen where there is one. Counts that name nobody. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `build`, `ref`, `bucket`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `build` | `object` | required |
| `app` | `string` | required |
| `appName` | `string` | required |
| `screen` | `string` | required |
| `name` | `string \| null` | required |
| `ref` | `string` | required |
| `bucket` | `"phone" \| "tablet" \| "desktop"` | required |
| `buckets` | `object[]` | required |
| `backdrop` | `object \| null` | required |
| `drawnWidth` | `integer \| null` | required |
| `pending` | `object \| null` | optional |
| `fields` | `object[]` | required |
| `cells` | `object[]` | required · at most 4000 items |
| `notDrawn` | `object` | required |
| `elements` | `object[]` | required · at most 50 items |
| `scroll` | `object` | required |
| `windowStart` | `string (date-time) \| null` | required |

### elementsAcrossBuilds

`GET /api/projects/:projectId/elements`

The same element followed across the project’s builds, with its clicks in each. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `elements` | `object[]` | required · at most 200 items |
| `unmatched` | `object` | required |
| `windowStart` | `string (date-time) \| null` | required |

### listFunnels

`GET /api/projects/:projectId/funnels/:build`

Each funnel of the project in one build, the tour’s ready-made one included, step by step: how many reached each step and who stopped where. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `build`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `build` | `object` | required |
| `funnels` | `object[]` | required |
| `tour` | `object \| null` | required |
| `limit` | `object` | required |
| `windowStart` | `string (date-time) \| null` | required |

### setFunnel

`PUT /api/projects/:projectId/funnels`

Makes or changes a funnel: a name and its steps in order. Without `commit` it is a rehearsal and changes nothing. One more than the plan keeps is refused, naming the plan that keeps more; the tour’s funnel never counts.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `id` | `string` | optional · not empty |
| `name` | `string` | required · 1–60 characters |
| `steps` | `object[]` | required · at most 8 items |
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `refusals` | `string[]` | required |
| `funnel` | `object \| null` | required |

### deleteFunnel

`POST /api/projects/:projectId/funnels/:funnelId/delete`

Deletes a funnel. Without `commit` it is a rehearsal and changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `funnelId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `refusals` | `string[]` | required |
| `funnel` | `object \| null` | required |

### projectReplays

`GET /api/projects/:projectId/replays`

The replays of the project’s visits that still open, newest first, on the plans that have replays. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `replays` | `object[]` | required · at most 200 items |
| `more` | `integer` | required |
| `replayDays` | `integer \| null` | required |
| `windowStart` | `string (date-time) \| null` | required |

### replayTimeline

`GET /api/visits/:visitId/replay`

One visit’s replay: its screens and clicks in the order and at the times they happened, over the platform’s own pictures of the screens. Never a recording of the screen, and never what was typed. A replay past its days is `404`. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `visitId`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `visitId` | `string` | required · not empty |
| `person` | `object` | required |
| `build` | `object` | required |
| `startedAt` | `string (date-time)` | required |
| `endedAt` | `string (date-time) \| null` | required |
| `durationSeconds` | `number` | required |
| `keptUntil` | `string (date-time)` | required |
| `segments` | `object[]` | required · at most 600 items |
| `events` | `object[]` | required · at most 3000 items |
| `moreEvents` | `integer` | required |
| `idle` | `object[]` | required |

### deleteReplay

`POST /api/visits/:visitId/replay/delete`

Deletes one visit’s replay for good, keeping the screens and clicks it was drawn from. Without `commit` it is a rehearsal and changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `visitId`

**Body:** `object`

| Field | Type | |
|---|---|---|
| `commit` | `boolean` | optional |

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `committed` | `boolean` | required |
| `visitId` | `string` | required · not empty |
| `person` | `object` | required |
| `startedAt` | `string (date-time)` | required |
| `keptUntil` | `string (date-time)` | required |

### exportInsight

`GET /api/projects/:projectId/export/:build/:table`

One table of what viewers did in a build (`screens`, `elements`, `fields` or `funnels`) as rows and columns, for a CSV: totals that name nobody. On Team and Enterprise. `truncated` says the rows stopped at the cap. Changes nothing.

Signed in: a session cookie (the app) or `Authorization: Bearer <token>` (the CLI and the connector).

**Path parameters:** `projectId`, `build`, `table`

**Body:** none

**Reply:** `object`

| Field | Type | |
|---|---|---|
| `reportedByTheDemo` | `true` | required |
| `table` | `"screens" \| "elements" \| "fields" \| "funnels"` | required |
| `build` | `object` | required |
| `filename` | `string` | required |
| `columns` | `string[]` | required |
| `rows` | `string \| number \| null[][]` | required · at most 5000 items |
| `truncated` | `boolean` | required |

> [!NOTE]
> Every workspace starts on Free, and moves to Pro or Team whenever you like, in Settings, Billing. Sign in at app.getroomi.com with GitHub or Google, then add the connector to Claude at https://mcp.getroomi.com/mcp, or run the CLI with npx @getroomi/cli. These pages describe the connector, the CLI, pitch.json, the app and the room as they are.
