HTTP API

Every endpoint of the platform API, drawn from the contract.

On this page

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

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 in the app (Settings → Claude & CLI → API tokens) and send it as the bearer:

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 and read that session's header with roomi auth header:

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 POSTs 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:

{ "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 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.

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:

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

{"kind":"static","sizeBytes":20480}
{ "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.

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:

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:

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.

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

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

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

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

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

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

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

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

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

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

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

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