HTTP API
Every endpoint of the platform API, drawn from the contract.
On this page
- Base URL
- Authentication
- Workspaces
- Requests and replies
- Errors
- Limits
- Deploying through the API
- Endpoints
- Projects, builds and links
- listProjects
- createProject
- getProject
- projectAllowance
- startUpload
- createBuild
- listBuilds
- makeLive
- buildLogs
- previewBuild
- endPreview
- createLink
- rehearseLink
- listLinks
- revokeLink
- revealLink
- reissueLink
- erasurePlan
- personErasurePlan
- eraseViewer
- listVisits
- listResponses
- listComments
- pipeline
- addPage
- listWorkspaces
- projectWorkspace
- createTeam
- listMembers
- setMemberRole
- removeMember
- leaveTeam
- renameWorkspace
- listInvitations
- createInvitation
- revokeInvitation
- viewInvitation
- acceptInvitation
- deleteTeam
- projectHistory
- getBilling
- billingCheckout
- billingPortal
- listInvoices
- invoiceLink
- Changing a project
- renameProject
- deleteProject
- moveProject
- getRoomSetup
- orderApps
- orderPages
- removePage
- orderFiles
- removeFile
- setViewerControls
- listFeedback
- resolveComment
- replyToComment
- Pausing a room
- getRoomPause
- pauseRoom
- resumeRoom
- projectHistory
- The tour
- getTour
- Analytics
- buildHistory
- journey
- viewerJourney
- projectAnalytics
- workspaceAnalytics
- projectEngagement
- workspaceEngagement
- projectAttention
- projectBuildEngagement
- projectPresence
- workspacePresence
- projectReactions
- The pipeline
- board
- projectBoard
- placeLink
- judgeLink
- followUp
- listNotes
- addNote
- removeNote
- placeViewer
- judgeViewer
- followUpViewer
- listViewerNotes
- addViewerNote
- followUpEvidence
- viewerFollowUpEvidence
- Feedback
- getFeedback
- Room setup
- getNextSteps
- setNextSteps
- getBrand
- setBrand
- removeLogo
- getTheme
- setTheme
- resetTheme
- checkTheme
- listThemePresets
- saveThemePreset
- renameThemePreset
- deleteThemePreset
- applyThemePreset
- getProfile
- setProfile
- The community
- getCard
- saveCard
- removeCover
- checkBuildCover
- coverFromBuild
- listProject
- rehearseListing
- appealListing
- listNotices
- readNotices
- scanCard
- unlistProject
- previewPass
- getAccess
- setAccess
- communityPass
- Arranging projects
- getArrangement
- arrangeProjects
- createGroup
- renameGroup
- deleteGroup
- Public
- profile
- listings
- Plan and usage
- getBilling
- projectBounces
- billingCheckout
- billingPortal
- billingChangePlan
- billingChooseFree
- billingRestore
- listInvoices
- invoiceLink
- You, and your workspace’s people
- whoami
- setName
- removePhoto
- deletable
- deleteAccount
- containerUsage
- members
- signIns
- disconnect
- sessions
- revokeSession
- signOutEverywhere
- Your first days
- myPreferences
- welcomeSeen
- foldFeedbackTab
- myOnboarding
- setOnboarding
- setTour
- sendProductFeedback
- Notifications
- myNotificationPreferences
- setNotificationPreference
- resubscribe
- myNotes
- replyOnNote
- Reports
- reportProject
- API tokens
- listTokens
- createToken
- revokeToken
- Your own domain
- listDomains
- addDomain
- checkDomain
- removeDomain
- Screens and clicks
- getRecording
- setRecording
- getPrivacyContact
- setPrivacyContact
- linkScreens
- viewerScreens
- projectScreens
- projectClicks
- screenHeatmap
- elementsAcrossBuilds
- listFunnels
- setFunnel
- deleteFunnel
- projectReplays
- replayTimeline
- deleteReplay
- exportInsight
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.comEvery 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
roomiuses, sent asAuthorization: Bearer <token>: the sessionroomi loginkeeps, 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 with400,{"error":"invalid"}, and anissueslist 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
GETanswers200. APOSTthat creates something (createProject,createBuild,createLink) answers201; otherPOSTs answer200. The upload'sPUTanswers204with 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, isnull. - 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: 20480It 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}/liveThe 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.htmlat 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 deploymakes from your image. Its manifest must carryrun, the start commandroomi deployreads from the image, so a container build is deployed withroomi deploy, not by hand.
Endpoints
Every endpoint, drawn from the contract the platform checks each request and
reply against. Paths show parameters as :name.
Projects, builds and links
The core of the contract: projects, uploads and builds, viewer links, and what viewers did and said. roomi and the connector call these.
listProjects
GET /api/projects
Every project in your workspace that has not been deleted, newest first, each with its room’s address. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
slug |
string |
required · 3–40 characters |
name |
string |
required |
visibility |
"private" | "public" |
required |
liveBuildId |
string | null |
required |
previewBuildId |
string | null |
optional |
roomUrl |
string (uri) |
required |
createdAt |
string (date-time) |
required |
createProject
POST /api/projects
Creates a project. Its slug is the room’s address; its name is what the room shows. Refused with 409 when the slug is taken or was deleted less than 30 days ago, 422 when it is not one the platform allows (format, reserved, impersonation, banned), and 402 beyond the plan’s projects.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
slug |
string |
required · 3–40 characters |
name |
string |
required · 1–80 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
slug |
string |
required · 3–40 characters |
name |
string |
required |
visibility |
"private" | "public" |
required |
liveBuildId |
string | null |
required |
previewBuildId |
string | null |
optional |
roomUrl |
string (uri) |
required |
createdAt |
string (date-time) |
required |
getProject
GET /api/projects/:projectId
One project of your workspace, by id. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
slug |
string |
required · 3–40 characters |
name |
string |
required |
visibility |
"private" | "public" |
required |
liveBuildId |
string | null |
required |
previewBuildId |
string | null |
optional |
roomUrl |
string (uri) |
required |
createdAt |
string (date-time) |
required |
projectAllowance
GET /api/allowance/projects
Whether createProject would make a new project now: the projects your workspace holds, paused ones included, the most its plan allows (null for no limit), and the refusal createProject would give, in its words, or null. roomi deploy and the connector’s deploy_static ask it when they rehearse a deploy to a new address. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
used |
integer |
required |
allowed |
integer | null |
required |
refusal |
string | null |
required |
startUpload
POST /api/projects/:projectId/uploads
Declares a build’s artefact before it is sent: its kind and its exact size in bytes, at most 512 MB. Returns the upload’s id and the address to PUT the bytes to, with Content-Length equal to the size declared; that PUT answers 204, and is refused if the size differs.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
kind |
"container" | "static" |
required |
sizeBytes |
integer |
required |
Reply: object
| Field | Type | |
|---|---|---|
uploadId |
string |
required · not empty |
putUrl |
string |
required |
createBuild
POST /api/projects/:projectId/builds
Registers a build from a finished upload on the same project, with its pitch.json. The build is not live until makeLive. A static build is unpacked here; a container build must carry run. Refused as unfinished, kind, used or archive, with 402 beyond the plan’s deploys and 423 while the platform has the project paused. rehearsal, optional, is what the deploy saw rehearsing each story step; the app shows a build without one as not reported, never as passed.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
uploadId |
string |
required · not empty |
manifest |
object |
required |
note |
string |
optional · at most 200 characters |
rehearsal |
object |
optional |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
projectId |
string |
required · not empty |
kind |
"container" | "static" |
required |
manifest |
object |
required |
sizeBytes |
integer |
required |
note |
string | null |
required |
live |
boolean |
required |
preview |
boolean |
optional |
createdAt |
string (date-time) |
required |
room |
"standard" | "immersive" |
optional |
listBuilds
GET /api/projects/:projectId/builds
Every build of the project, newest first, each saying whether it is the live one. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
projectId |
string |
required · not empty |
kind |
"container" | "static" |
required |
manifest |
object |
required |
sizeBytes |
integer |
required |
note |
string | null |
required |
live |
boolean |
required |
preview |
boolean |
optional |
createdAt |
string (date-time) |
required |
room |
"standard" | "immersive" |
optional |
makeLive
POST /api/projects/:projectId/builds/:buildId/live
Makes one of the project’s builds the live one, the build its room shows. The same call makes an earlier build live again, which is a rollback (roomi rollback), and makes the build being previewed live, which ends the preview. Who did it and when is recorded.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, buildId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
projectId |
string |
required · not empty |
kind |
"container" | "static" |
required |
manifest |
object |
required |
sizeBytes |
integer |
required |
note |
string | null |
required |
live |
boolean |
required |
preview |
boolean |
optional |
createdAt |
string (date-time) |
required |
room |
"standard" | "immersive" |
optional |
buildLogs
GET /api/projects/:projectId/builds/:buildId/logs
What a container build’s running copies wrote to standard output and standard error, oldest first, with the viewer whose copy wrote each line, redacted of anything that looks like a secret. Each copy keeps its newest 2,000 lines while it runs and none once it stops; said says why there are none. Pass the reply’s cursor back as ?after= for the lines written since. A static build has none. Another workspace’s build is 404. Changes nothing, and does not keep a copy awake.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, buildId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
buildId |
string |
required · not empty |
kind |
"container" | "static" |
required |
running |
integer |
required |
lines |
object[] |
required |
cursor |
string |
required |
said |
string | null |
required |
previewBuild
POST /api/projects/:projectId/builds/:buildId/preview
Makes one of the project’s builds its preview: it does not go live, and no viewer link, public address or Community card shows it. The project’s members see it through the members’ preview (previewPass) until makeLive makes it live or endPreview ends it; a newer preview replaces it. Refused with 422 as live for the build that is live already. Recorded in the project’s history.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, buildId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
projectId |
string |
required · not empty |
kind |
"container" | "static" |
required |
manifest |
object |
required |
sizeBytes |
integer |
required |
note |
string | null |
required |
live |
boolean |
required |
preview |
boolean |
optional |
createdAt |
string (date-time) |
required |
room |
"standard" | "immersive" |
optional |
endPreview
POST /api/projects/:projectId/preview/end
Ends the preview: the members’ preview shows the live build again. The build stays in the project’s builds. Refused with 422 as no-preview when nothing is being previewed. Recorded in the project’s history.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
slug |
string |
required · 3–40 characters |
name |
string |
required |
visibility |
"private" | "public" |
required |
liveBuildId |
string | null |
required |
previewBuildId |
string | null |
optional |
roomUrl |
string (uri) |
required |
createdAt |
string (date-time) |
required |
createLink
POST /api/projects/:projectId/links
Makes a private link to the room for one named viewer, with their email if you give it and an expiry of 1 to 365 days if you want one. Nothing is sent to the email unless you also give send: true: then the platform emails the viewer their link on your behalf, from its own address, naming you by the name you chose (and your team, from a team’s workspace), once. The reply carries the link’s full address; no list does, and revealLink returns it again. Refused with 402 on a plan without private links, beyond the plan’s links per project, or once the month’s viewer-hours are used; with send, refused whole, nothing made, as send (422) when a safeguard says no, and with 429 past the workspace’s emailed links for the hour or the day. A link that was emailed lists when (emailedAt).
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
viewerName |
string |
required · 1–80 characters |
viewerEmail |
string (email) |
optional |
expiresInDays |
integer |
optional · 1–365 |
send |
boolean |
optional |
Reply: object
| Field | Type | |
|---|---|---|
link |
object |
required |
url |
string (uri) |
required |
rehearseLink
POST /api/projects/:projectId/links/rehearsal
What createLink would do with the same body, with nothing made or sent: every check it makes and, with send: true, every safeguard its email must pass, then who the email would say it is from and its subject. Refused exactly as createLink would be. A connection that may only read is refused with 403, as for every POST.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
viewerName |
string |
required · 1–80 characters |
viewerEmail |
string (email) |
optional |
expiresInDays |
integer |
optional · 1–365 |
send |
boolean |
optional |
Reply: object
| Field | Type | |
|---|---|---|
viewerName |
string |
required |
expiresAt |
string (date-time) | null |
required |
email |
object | null |
required |
listLinks
GET /api/projects/:projectId/links
Every link of the project, each with its stage in the pipeline and whether its address can be shown again (recoverable), never the address. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
revokeLink
POST /api/links/:linkId/revoke
Revokes a link: it stops opening the room at once, and cannot be opened again. What its viewer already did stays on record.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
revealLink
POST /api/links/:linkId/reveal
A link’s full address again, to copy and resend when the viewer has lost it. Recorded in the project’s history with who asked. Refused with 422 as revoked or expired when the link no longer opens the room, and as unrecoverable for a link made before 1 October 2026, when only a hash of its key was kept: reissue that one. A connection that may only read is refused with 403, because the address opens the room. Sent with Cache-Control: no-store.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
link |
object |
required |
url |
string (uri) |
required |
reissueLink
POST /api/links/:linkId/reissue
A new address for the same link: the same viewer, with their visits, answers and comments, under a new key. The old address stops opening the room the moment it lands. For a link made before addresses were kept, or one that has gone astray; refused as revoked or expired like revealLink. Recorded in the project’s history.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
link |
object |
required |
url |
string (uri) |
required |
erasurePlan
GET /api/links/:linkId/erase
What erasing everyone under one private link would take, counted by table, with the pictures of the screen that would go and whose link it is. Changes nothing: ask it before eraseViewer.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
committed |
boolean |
required |
linkId |
string |
required |
viewerId |
string | null |
required |
name |
string | null |
required |
linkItself |
boolean |
required |
staying |
integer |
required |
rows |
{ [key]: integer } |
required |
files |
integer |
required |
personErasurePlan
GET /api/links/:linkId/people/:viewerId/erase
The same for one person under the link: someone it was passed on to, or the person it was made for, whose erasure takes the link’s own name and email too. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId, viewerId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
committed |
boolean |
required |
linkId |
string |
required |
viewerId |
string | null |
required |
name |
string | null |
required |
linkItself |
boolean |
required |
staying |
integer |
required |
rows |
{ [key]: integer } |
required |
files |
integer |
required |
eraseViewer
POST /api/links/:linkId/erase
Erases one viewer’s data: everyone under the link, or the one person viewerId names. Their visits, the moments of each, comments with their threads and pictures, answers, reactions, claims, meetings and your notes are deleted, and the emails about their meetings keep nothing of the address or the words. Erasing the whole link, or the person it was made for, takes the link’s name and email and stops it opening the room. Cannot be undone. Recorded in the project’s history, naming no one.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: object
| Field | Type | |
|---|---|---|
viewerId |
string |
optional · 1–100 characters |
Reply: object
| Field | Type | |
|---|---|---|
committed |
boolean |
required |
linkId |
string |
required |
viewerId |
string | null |
required |
name |
string | null |
required |
linkItself |
boolean |
required |
staying |
integer |
required |
rows |
{ [key]: integer } |
required |
files |
integer |
required |
listVisits
GET /api/projects/:projectId/visits
Every visit to the project’s room, with the seconds spent on each app and page. A preview records none. Pro and up: on Free it is refused with 402, as each viewer’s journey is, and total views are on the analytics endpoints. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string | null |
required |
viewerName |
string | null |
required |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
startedAt |
string (date-time) |
required |
endedAt |
string (date-time) | null |
required |
time |
{ [key]: integer } |
required |
entered |
"declare" | "password" | "email" | "door" | null |
optional |
listResponses
GET /api/projects/:projectId/responses
Every answer viewers gave to “What happens next”, with the detail they added. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string |
required · not empty |
viewerName |
string |
required |
step |
"meeting" | "yes" | "later" | "colleague" | "question" | "no" |
required |
detail |
{ [key]: any } | null |
required |
createdAt |
string (date-time) |
required |
listComments
GET /api/projects/:projectId/comments
Every comment viewers left in the project’s room, with the app and screen it was pinned to and whether it is resolved. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string | null |
required |
viewerName |
string | null |
required |
appId |
string | null |
required |
screen |
string | null |
required |
body |
string |
required |
resolvedAt |
string (date-time) | null |
required |
createdAt |
string (date-time) |
required |
position |
object | null |
required |
area |
object | null |
required |
device |
"phone" | "tablet" | "laptop" | "screen" | "none" | null |
required |
hasScreenshot |
boolean |
required |
pipeline
GET /api/pipeline
Every viewer link across every project in the workspace, with its stage: sent, opened, engaged, yes, later or no. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
projectId |
string |
required · not empty |
projectName |
string |
required |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
addPage
POST /api/projects/:projectId/pages
Adds a Markdown or HTML page to the project’s room, which every viewer sees at once. A page with the title of one the room already has replaces that page’s content.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
title |
string |
required · 1–80 characters |
kind |
"markdown" | "html" |
required |
content |
string |
required · at most 2000000 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
title |
string |
required |
kind |
"markdown" | "html" |
required |
listWorkspaces
GET /api/workspaces
Every workspace you belong to: your own first, then each team, with your role in each (owner or member), which one this session is working in (active), and the brand its plan shows (brand: its name and whether it has a logo, read from GET /api/workspaces/:workspaceId/logo; null for none). Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
name |
string |
required |
kind |
"personal" | "team" |
required |
role |
"owner" | "member" |
required |
active |
boolean |
required |
brand |
object | null |
optional |
projectWorkspace
GET /api/project-workspace/:slug
Which of your workspaces holds the live project at this address (workspaceId, its name and kind, and active when this session is working in it already), for a link made in another workspace than the one this session is working in. Only your own workspaces are asked: a project in a workspace you are not in is the same 404 as an address with no project. Changes nothing; moving the session there is Better Auth’s set-active, as the app’s switcher does.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: slug
Body: none
Reply: object
| Field | Type | |
|---|---|---|
workspaceId |
string |
required · not empty |
name |
string |
required |
kind |
"personal" | "team" |
required |
active |
boolean |
required |
createTeam
POST /api/workspaces
Makes a team with the name given, with you as its owner, and answers it. A new team has no plan, so it holds no projects and nobody else until it has Team or Enterprise; you may have one such team at a time (422, reason: unlicensed). Your own workspace is unchanged.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–80 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
name |
string |
required |
kind |
"personal" | "team" |
required |
role |
"owner" | "member" |
required |
active |
boolean |
required |
brand |
object | null |
optional |
listMembers
GET /api/workspaces/:workspaceId/members
Everyone in a workspace you belong to, owners first, each with their name, email, picture, role and when they joined; you marks you. Your own workspace has only you. Changes nothing; another workspace is a 404.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
displayName |
string |
required |
email |
string |
required |
image |
string | null |
required |
role |
"owner" | "member" |
required |
joinedAt |
string (date-time) |
required |
you |
boolean |
required |
setMemberRole
POST /api/workspaces/:workspaceId/members/:userId/role
Makes someone in a team an owner or a member. An owner’s to do (403, reason: permission, for a member), and refused (422, reason: team) when it would leave the team with no owner. Answers the team’s people.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId, userId
Body: object
| Field | Type | |
|---|---|---|
role |
"owner" | "member" |
required |
Reply: object[]
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
displayName |
string |
required |
email |
string |
required |
image |
string | null |
required |
role |
"owner" | "member" |
required |
joinedAt |
string (date-time) |
required |
you |
boolean |
required |
removeMember
POST /api/workspaces/:workspaceId/members/:userId/remove
Takes someone out of a team at once: from their next request they reach none of it. An owner’s to do; never yourself, which is leaveTeam. Answers the team’s people.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId, userId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
displayName |
string |
required |
email |
string |
required |
image |
string | null |
required |
role |
"owner" | "member" |
required |
joinedAt |
string (date-time) |
required |
you |
boolean |
required |
leaveTeam
POST /api/workspaces/:workspaceId/leave
Takes you out of a team. An owner leaves only while another owner stays (422, reason: team), and your own workspace is never left.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
left |
true |
required |
renameWorkspace
POST /api/workspaces/:workspaceId/name
Renames a team, or your own workspace. An owner’s to do. Your own workspace’s name is what a room shows its viewers for a link made before display names.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–80 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
name |
string |
required |
kind |
"personal" | "team" |
required |
role |
"owner" | "member" |
required |
active |
boolean |
required |
brand |
object | null |
optional |
listInvitations
GET /api/workspaces/:workspaceId/invitations
A team’s invitations still waiting and not expired, each with its email, who made it and when it expires. An owner’s to see. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
email |
string |
required |
role |
"owner" | "member" |
required |
invitedBy |
string |
required |
createdAt |
string (date-time) |
required |
expiresAt |
string (date-time) |
required |
createInvitation
POST /api/workspaces/:workspaceId/invitations
Invites one email into a team and answers the invitation with url, the link to send: nothing is emailed. Only someone signed in with that email, verified as theirs, can use the link, once, within 7 days. An owner’s to do; a waiting invitation holds a seat, so a team at its plan’s seats is refused (422, reason: team), and so is someone in the team already or invited already.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId
Body: object
| Field | Type | |
|---|---|---|
email |
string (email) |
required · at most 254 characters |
Reply: object
| Field | Type | |
|---|---|---|
invitation |
object |
required |
url |
string (uri) |
required |
revokeInvitation
POST /api/workspaces/:workspaceId/invitations/:invitationId/revoke
Revokes an invitation still waiting: its link stops working at once. An owner’s to do. Answers the invitations still waiting.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId, invitationId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
email |
string |
required |
role |
"owner" | "member" |
required |
invitedBy |
string |
required |
createdAt |
string (date-time) |
required |
expiresAt |
string (date-time) |
required |
viewInvitation
GET /api/invitations/:invitationId
An invitation, told only to the person signed in with the email it is for: the team’s name and who invited them. A used, revoked or expired invitation, or anyone else’s, is a 404. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: invitationId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
workspaceId |
string |
required · not empty |
workspaceName |
string |
required |
invitedBy |
string |
required |
expiresAt |
string (date-time) |
required |
acceptInvitation
POST /api/invitations/:invitationId/accept
Joins the team the invitation is for, as a member, and answers the team. Only the invited person, once, while a seat is free (422, reason: team, when none is). The joining is written in the team’s record.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: invitationId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
name |
string |
required |
kind |
"personal" | "team" |
required |
role |
"owner" | "member" |
required |
active |
boolean |
required |
brand |
object | null |
optional |
deleteTeam
POST /api/workspaces/:workspaceId/delete
Deletes a team, with its name typed again as confirm: its name, brand, people and invitations. An owner’s to do, and only once it holds no live project and its plan is cancelled (422, reason: team). Everyone in it keeps their own workspace.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: workspaceId
Body: object
| Field | Type | |
|---|---|---|
confirm |
string |
required |
Reply: object
| Field | Type | |
|---|---|---|
deleted |
true |
required |
projectHistory
GET /api/projects/:projectId/history
Every pause, change of note and resume on the project, and every link copied again (link.copy) or reissued (link.reissue) with whose it was, newest first, with who did it while they are a member. Append-only. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
kind |
"room.pause" | "room.message" | "room.resume" | "link.copy" | "link.reissue" | "room.busy" | "build.preview" | "build.preview-end" | "viewer.erase" | "domain.add" | "domain.active" | "domain.failed" | "domain.remove" | "entry.password" | "entry.password-removed" | "entry.email" | "entry.email-off" |
required |
by |
string | null |
required |
message |
string | null |
required |
viewer |
string | null |
required |
until |
string (date-time) | null |
required |
domain |
string | null |
required |
at |
string (date-time) |
required |
getBilling
GET /api/billing
Your workspace’s plan and its status, its seats, this month’s usage, the viewer-hours allowance and where it stands, and whether the workspace is suspended. Also whether paid plans are open (paidPlans), whether you may manage billing and see invoices, a change waiting for the period’s end, and any payment not made: its stage (grace, frozen, free), what is owed, and the dates it freezes, moves to Free and is written off (lifecycle). Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
plan |
"free" | "pro" | "team" | "organisation" | "solo" | "studio" | "agency" | "enterprise" |
required |
kind |
"personal" | "team" |
optional |
seats |
object |
optional |
interval |
"month" | "year" | null |
required |
status |
"active" | "past_due" | "canceled" |
required |
currentPeriodEnd |
string (date-time) | null |
required |
usage |
object |
required |
allowance |
object |
required |
history |
object |
optional |
suspended |
boolean |
required |
paidPlans |
"off" | "open" |
required |
immersive |
boolean |
optional |
canManage |
boolean |
optional |
canSeeInvoices |
boolean |
optional |
subscribed |
boolean |
optional |
cancelAtPeriodEnd |
boolean |
optional |
selected |
object | null |
optional |
grace |
object | null |
optional |
frozen |
boolean |
optional |
lifecycle |
object | null |
optional |
billingCheckout
POST /api/billing/checkout
Stripe’s hosted Checkout for a paid plan (pro, or team with seats from 2 to 5, by month or year): the address to send the person to. VAT is added by Stripe Tax from the billing address; a VAT number can be given. It grants nothing: the plan changes when Stripe confirms the payment. A team’s owners only, or the person in their own workspace (403 otherwise). Refused with 422 for a plan the workspace’s kind does not hold (Team for a person, Pro for a team), for seats outside the plan’s (a sixth is Enterprise, by arrangement: contact sales), for a workspace that already pays or still owes for a plan it lost.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
plan |
"pro" | "team" |
required |
interval |
"month" | "year" |
required |
seats |
integer |
optional · at most 1000 |
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
billingPortal
POST /api/billing/portal
Stripe’s customer portal for the workspace: the card, the billing address and VAT number, and cancelling at the period’s end. Plans and seats are changed with POST /api/billing/plan, not there. After a failed payment it opens on updating the card. Owners only; 422 until the workspace has paid for something. Open while the workspace is frozen.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
listInvoices
GET /api/billing/invoices
Every invoice and receipt the workspace has had, newest first: its number, date, period, total, VAT, status, any refund, and whether it is still owed. No links: ask POST /api/billing/invoices/{invoiceId}/link for one. Owners only (403 otherwise); open while the workspace is frozen. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
number |
string | null |
required |
status |
"paid" | "open" | "failed" | "void" |
required |
createdAt |
string (date-time) |
required |
periodStart |
string (date-time) | null |
required |
periodEnd |
string (date-time) | null |
required |
subtotalPence |
integer | null |
required |
taxPence |
integer | null |
required |
totalPence |
integer |
required |
refundedPence |
integer |
required |
currency |
string | null |
required |
owed |
boolean |
required |
invoiceLink
POST /api/billing/invoices/:invoiceId/link
Links to one invoice, asked of Stripe each time and never kept, since they expire: its PDF, and its page on Stripe, where an open invoice is paid and a paid one’s receipt is downloaded. Owners only; another workspace’s invoice is 404. Open while the workspace is frozen. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: invoiceId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
pdfUrl |
string (uri) | null |
required |
pageUrl |
string (uri) | null |
required |
owed |
boolean |
required |
Changing a project
Renaming and deleting a project, the room’s order and its pages, and answering feedback.
renameProject
POST /api/projects/:projectId/name
Changes the project’s name, as the room and the app show it. The slug, and so the room’s address, stays as it is.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–80 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
slug |
string |
required · 3–40 characters |
name |
string |
required |
visibility |
"private" | "public" |
required |
liveBuildId |
string | null |
required |
previewBuildId |
string | null |
optional |
roomUrl |
string (uri) |
required |
createdAt |
string (date-time) |
required |
deleteProject
POST /api/projects/:projectId/delete
Deletes the project. confirm must be the project’s slug, or it is refused as confirm. Its links stop opening the room, and its slug is held for 30 days.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
confirm |
string |
required |
Reply: object
| Field | Type | |
|---|---|---|
deleted |
true |
required |
moveProject
POST /api/projects/:projectId/move
Moves the project, with its builds, links, viewers, feedback, pipeline, bookings, pages, files, community card and its own domain, into another workspace you belong to (to). Out of a team needs one of its owners; into one, any member; a workspace you are not in is 404. Without commit it is a rehearsal: plan says what would move, what viewers would see differently, who is told and what refuses it, and nothing changes. With commit: true it moves only if plan.refusals is empty; every link keeps opening the same room. An API token cannot reach it.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
to |
string |
required · 1–100 characters |
commit |
boolean |
optional |
Reply: object
| Field | Type | |
|---|---|---|
rehearsal |
boolean |
required |
moved |
boolean |
required |
plan |
object |
required |
detail |
string |
required |
getRoomSetup
GET /api/projects/:projectId/room
The room’s order: the apps as you ordered them (null for pitch.json’s order), the pages as the rail lists them, the files listed after them, and which controls the room offers its viewers (controls). Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
orderApps
POST /api/projects/:projectId/room/apps
Sets the order the room’s switcher lists the apps in. The apps it names come first, in its order, then any it leaves out, in pitch.json’s; an id the live build does not have is ignored.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
ids |
string[] |
required · at most 100 items |
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
orderPages
POST /api/projects/:projectId/room/pages
Sets the order the rail lists the pages in. The list must name every page of the project exactly once, or it is refused as order.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
ids |
string[] |
required · at most 100 items |
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
removePage
POST /api/projects/:projectId/pages/:pageId/remove
Takes a page out of the room and deletes its content. The pages after it close ranks. It is uploaded again by the next deploy if pitch.json still lists it.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, pageId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
orderFiles
POST /api/projects/:projectId/room/files
Sets the order the rail lists the files in, after the pages. The list must name every file of the project exactly once, or it is refused as order.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
ids |
string[] |
required · at most 100 items |
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
removeFile
POST /api/projects/:projectId/files/:fileId/remove
Takes a file out of the room and deletes it. The files after it close ranks. A file is added with PUT /api/projects/:projectId/files?title=…: its own bytes, a PDF of up to 20 MB or a PNG, JPEG or WebP image of up to 5 MB, sent as what it is (415 otherwise); a room holds up to 20.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, fileId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
setViewerControls
POST /api/projects/:projectId/room/controls
Which controls the room offers its viewers, every one named, each true or false: frame, fullscreen, newTab, phone, scenarios, comments, reactions and nextSteps. One switched off is gone from the room at once, and the room refuses it if a viewer asks for it anyway.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
controls |
object |
required |
Reply: object
| Field | Type | |
|---|---|---|
appOrder |
string[] | null |
required |
pages |
object[] |
required |
files |
object[] |
required |
controls |
object |
required |
listFeedback
GET /api/projects/:projectId/feedback
Every comment on the project, with your reply to it and whether it is resolved. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string | null |
required |
viewerName |
string | null |
required |
appId |
string | null |
required |
screen |
string | null |
required |
body |
string |
required |
resolvedAt |
string (date-time) | null |
required |
createdAt |
string (date-time) |
required |
position |
object | null |
required |
area |
object | null |
required |
device |
"phone" | "tablet" | "laptop" | "screen" | "none" | null |
required |
hasScreenshot |
boolean |
required |
reply |
string | null |
required |
repliedAt |
string (date-time) | null |
required |
from |
object | null |
required |
resolveComment
POST /api/comments/:commentId/resolve
Marks a comment resolved, or, with false, not resolved again.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: commentId
Body: object
| Field | Type | |
|---|---|---|
resolved |
boolean |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string | null |
required |
viewerName |
string | null |
required |
appId |
string | null |
required |
screen |
string | null |
required |
body |
string |
required |
resolvedAt |
string (date-time) | null |
required |
createdAt |
string (date-time) |
required |
position |
object | null |
required |
area |
object | null |
required |
device |
"phone" | "tablet" | "laptop" | "screen" | "none" | null |
required |
hasScreenshot |
boolean |
required |
reply |
string | null |
required |
repliedAt |
string (date-time) | null |
required |
from |
object | null |
required |
replyToComment
POST /api/comments/:commentId/reply
Answers a viewer’s comment; the viewer sees the answer in the room. One answer per comment: answering again replaces it.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: commentId
Body: object
| Field | Type | |
|---|---|---|
body |
string |
required · 1–2000 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string | null |
required |
viewerName |
string | null |
required |
appId |
string | null |
required |
screen |
string | null |
required |
body |
string |
required |
resolvedAt |
string (date-time) | null |
required |
createdAt |
string (date-time) |
required |
position |
object | null |
required |
area |
object | null |
required |
device |
"phone" | "tablet" | "laptop" | "screen" | "none" | null |
required |
hasScreenshot |
boolean |
required |
reply |
string | null |
required |
repliedAt |
string (date-time) | null |
required |
from |
object | null |
required |
Pausing a room
Closing every link to a project’s room for now, with a note to viewers, opening it again, and the project’s history of both.
getRoomPause
GET /api/projects/:projectId/pause
Where the room stands: your pause (when, by whom, and the note to viewers), any pause of the platform’s (over-limit, suspended, takedown), and what a viewer with a working link meets now: room, paused or unavailable. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
owner |
object | null |
required |
system |
"over-limit" | "suspended" | "takedown" | null |
required |
viewers |
"room" | "paused" | "unavailable" |
required |
pauseRoom
POST /api/projects/:projectId/pause
Pauses the room: every working link shows a page saying who paused it, with message under it (at most 280 characters, or null for none), and no demo starts. Links, builds and pages are untouched, and deploys and new links still work. Called on a paused room, it changes the note. Recorded in the project’s history.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
message |
string | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
owner |
object | null |
required |
system |
"over-limit" | "suspended" | "takedown" | null |
required |
viewers |
"room" | "paused" | "unavailable" |
required |
resumeRoom
POST /api/projects/:projectId/resume
Lifts your pause, so the same links open the room again. A pause of the platform’s stays, and the reply says so. Refused as taken when the room is not paused. Recorded in the project’s history.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
owner |
object | null |
required |
system |
"over-limit" | "suspended" | "takedown" | null |
required |
viewers |
"room" | "paused" | "unavailable" |
required |
projectHistory
GET /api/projects/:projectId/history
Every pause, change of note and resume on the project, and every link copied again (link.copy) or reissued (link.reissue) with whose it was, newest first, with who did it while they are a member. Append-only. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
kind |
"room.pause" | "room.message" | "room.resume" | "link.copy" | "link.reissue" | "room.busy" | "build.preview" | "build.preview-end" | "viewer.erase" | "domain.add" | "domain.active" | "domain.failed" | "domain.remove" | "entry.password" | "entry.password-removed" | "entry.email" | "entry.email-off" |
required |
by |
string | null |
required |
message |
string | null |
required |
viewer |
string | null |
required |
until |
string (date-time) | null |
required |
domain |
string | null |
required |
at |
string (date-time) |
required |
The tour
The live build’s story, step by step, beside what its deploy reported of rehearsing each step.
getTour
GET /api/projects/:projectId/tour
The live build’s story, step by step: each step’s app, its calls, and how its rehearsal went (passed, failed, nothing-to-run or not-reported), with what the demo last said. build is null when nothing is live. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
build |
object | null |
required |
steps |
object[] |
required |
reported |
boolean |
required |
Analytics
Build history, each viewer’s journey through the room, and analytics over a range of days.
buildHistory
GET /api/projects/:projectId/builds/history
Every build of the project, newest first, with who deployed it and each time it was made live, so the app can show what was live when. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
projectId |
string |
required · not empty |
kind |
"container" | "static" |
required |
manifest |
object |
required |
sizeBytes |
integer |
required |
note |
string | null |
required |
live |
boolean |
required |
preview |
boolean |
optional |
createdAt |
string (date-time) |
required |
room |
"standard" | "immersive" |
optional |
deployedBy |
object | null |
required |
releases |
object[] |
required |
journey
GET /api/links/:linkId/journey
The journey of the person a link was made for: their visits in order, what they opened, ran, said and chose, where they stopped, and how far they took the tour, with everyone who opened the link. Anyone it was passed on to has a journey of their own (viewerJourney), and none of it is in this one. Refused with 402 on a plan without analytics in full. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
person |
object |
optional |
link |
object |
required |
people |
object[] |
required |
sessions |
object[] |
required |
outside |
object[] |
required |
tour |
object | null |
required |
windowStart |
string (date-time) | null |
optional |
viewerJourney
GET /api/viewers/:viewerId/journey
The journey of someone a link was passed on to, who said who they were: their own visits, moments and answers alone, with the name the link was made for. Another workspace’s person is a 404. Refused with 402 on a plan without analytics in full. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
person |
object |
optional |
link |
object |
required |
people |
object[] |
required |
sessions |
object[] |
required |
outside |
object[] |
required |
tour |
object | null |
required |
windowStart |
string (date-time) | null |
optional |
projectAnalytics
GET /api/projects/:projectId/analytics/:from/:to
One project’s analytics over a range of UTC days, written YYYY-MM-DD, both ends included, at most 366 days. In full on a plan with it; total views only on one without. A range that is not days, or ends before it starts, is refused as range.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, from, to
Body: none
Reply: object
workspaceAnalytics
GET /api/analytics/:from/:to
The same as projectAnalytics, across every project in the workspace, with the split by project.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: from, to
Body: none
Reply: object
projectEngagement
GET /api/projects/:projectId/engagement
Every viewer on the project — the person each link was made for, and each person a link was passed on to, as a viewer of their own — hottest first by what they did (most recently seen, then return visits, people brought in, comments and questions, time inside), with that evidence in words; the summary (shared with, opened, average time inside, ready to talk, comments waiting for a reply) and the funnel from shared to ready. From the plan’s history window on. Total views only on a plan without analytics in full. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
workspaceEngagement
GET /api/engagement
The same as projectEngagement, across every project in the workspace. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
projectAttention
GET /api/projects/:projectId/attention/:from/:to
Seconds on each app and page of the room per UTC day, as a grid of sections by days, the busiest of them, and each private viewer’s own split. A visit’s seconds count on the day it began. Total views only on a plan without analytics in full. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId, from, to
Body: none
Reply: object
projectBuildEngagement
GET /api/projects/:projectId/builds/engagement
What each build of one project met while it was live, newest first: visits, people, seconds inside and per person, how many came back (a visit an hour or more after their visit before, to any build), comments, and the three sections that held the most time. Each visit records the build live when it began; visits from before that was recorded (12 October 2026) are counted apart in unrecorded, never put in a build. From the plan’s history window on. Total views only on a plan without analytics in full. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
projectPresence
GET /api/projects/:projectId/presence
Who is in the room now: each private viewer whose room page reported in the last 45 seconds and has not left, by name and with what they are on, and how many people are at the public address, never named. A count alone on a plan without analytics in full. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
workspacePresence
GET /api/presence
The same as projectPresence, across every room in the workspace. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
projectReactions
GET /api/projects/:projectId/reactions
What viewers reacted with in the project’s room (a heart, a clap, a fire): each person on a private link by name, with when each went on, and the public address’s as counts. For you and your team alone: viewers never see each other’s. On a plan without analytics in full, the public address’s counts only. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
The pipeline
Each viewer as a card to work: placed in a stage, judged, followed up and noted. Pro and up: on Free every endpoint here is refused with 402.
board
GET /api/board
Every viewer on every project that has not been deleted, as a card — the person each link was made for, and each person a link was passed on to, with a card of their own: its stage, the stage the evidence suggests, the outcome, the follow-up, your notes and the signals behind it. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
projectBoard
GET /api/projects/:projectId/board
One project’s links, as cards. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
placeLink
POST /api/links/:linkId/stage
Places a viewer in a stage by hand, over what the evidence says; the evidence’s stage is still offered as a suggestion. null hands them back to the evidence.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: object
| Field | Type | |
|---|---|---|
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
judgeLink
POST /api/links/:linkId/outcome
Marks the deal won, lost or later. null clears it.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: object
| Field | Type | |
|---|---|---|
outcome |
"won" | "lost" | "later" | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
followUp
POST /api/links/:linkId/follow-up
Sets the day to follow this viewer up, and a line on what about. Both null clears it. Nothing is sent to anyone.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: object
| Field | Type | |
|---|---|---|
on |
string | null |
required |
note |
string | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
listNotes
GET /api/links/:linkId/notes
Your workspace’s notes on one viewer, newest first. They are never shown in the room. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string |
required · not empty |
body |
string |
required |
by |
string | null |
required |
byImage |
string | null |
required |
createdAt |
string (date-time) |
required |
addNote
POST /api/links/:linkId/notes
Adds a note on one viewer, and returns all of their notes. Notes are never shown in the room.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: object
| Field | Type | |
|---|---|---|
body |
string |
required · 1–2000 characters |
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string |
required · not empty |
body |
string |
required |
by |
string | null |
required |
byImage |
string | null |
required |
createdAt |
string (date-time) |
required |
removeNote
POST /api/notes/:noteId/remove
Removes one note, and returns the remaining notes on the same viewer.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: noteId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string |
required · not empty |
body |
string |
required |
by |
string | null |
required |
byImage |
string | null |
required |
createdAt |
string (date-time) |
required |
placeViewer
POST /api/viewers/:viewerId/stage
The same as placeLink, for someone a link was passed on to: their card is their own, and placing them never moves the person the link was made for.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: object
| Field | Type | |
|---|---|---|
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
judgeViewer
POST /api/viewers/:viewerId/outcome
The same as judgeLink, for someone a link was passed on to.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: object
| Field | Type | |
|---|---|---|
outcome |
"won" | "lost" | "later" | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
followUpViewer
POST /api/viewers/:viewerId/follow-up
The same as followUp, for someone a link was passed on to. Nothing is sent to anyone.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: object
| Field | Type | |
|---|---|---|
on |
string | null |
required |
note |
string | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
viewerName |
string |
required |
viewerEmail |
string (email) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
recoverable |
boolean |
optional |
emailedAt |
string (date-time) | null |
optional |
viewerId |
string | null |
optional |
origin |
"named" | "forwarded" |
optional |
via |
string | null |
optional |
linkId |
string |
optional · not empty |
projectId |
string |
required · not empty |
projectName |
string |
required |
suggested |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
placed |
boolean |
required |
outcome |
"won" | "lost" | "later" | null |
required |
followUp |
object |
required |
notes |
integer |
required |
signals |
object |
required |
forwarded |
object[] |
required |
claims |
integer |
required |
listViewerNotes
GET /api/viewers/:viewerId/notes
Your workspace’s notes on someone a link was passed on to, newest first. Never shown in the room. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string |
required · not empty |
body |
string |
required |
by |
string | null |
required |
byImage |
string | null |
required |
createdAt |
string (date-time) |
required |
addViewerNote
POST /api/viewers/:viewerId/notes
Adds a note on someone a link was passed on to, and returns all of their notes.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: object
| Field | Type | |
|---|---|---|
body |
string |
required · 1–2000 characters |
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string |
required · not empty |
body |
string |
required |
by |
string | null |
required |
byImage |
string | null |
required |
createdAt |
string (date-time) |
required |
followUpEvidence
GET /api/links/:linkId/follow-up/evidence
Exactly what the person a link was made for did, to write their follow-up from: each visit (when, how long, where the time went, what they opened and ran), how far the tour took them, their comments in their own words, their answers, the evidence in words, and your notes on them. Theirs alone, from the plan’s history window on. Refused with 402 on a plan without analytics in full or the pipeline. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: linkId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
viewer |
object |
required |
project |
object |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
evidence |
string[] |
required |
visits |
object[] |
required |
tour |
object | null |
required |
comments |
object[] |
required |
answers |
object[] |
required |
notes |
object[] |
required |
windowStart |
string (date-time) | null |
required |
viewerFollowUpEvidence
GET /api/viewers/:viewerId/follow-up/evidence
The same as followUpEvidence, for someone a link was passed on to: their own visits, comments and answers, and your notes on them alone.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: viewerId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
viewer |
object |
required |
project |
object |
required |
stage |
"sent" | "opened" | "engaged" | "yes" | "later" | "no" |
required |
evidence |
string[] |
required |
visits |
object[] |
required |
tour |
object | null |
required |
comments |
object[] |
required |
answers |
object[] |
required |
notes |
object[] |
required |
windowStart |
string (date-time) | null |
required |
Feedback
One comment a viewer left, in full.
getFeedback
GET /api/comments/:commentId
One comment in full: where on the stage it was pinned, the app’s name, whether a screenshot came with it, your reply, and the viewer who left it with their stage. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: commentId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
linkId |
string | null |
required |
viewerName |
string | null |
required |
appId |
string | null |
required |
screen |
string | null |
required |
body |
string |
required |
resolvedAt |
string (date-time) | null |
required |
createdAt |
string (date-time) |
required |
position |
object | null |
required |
area |
object | null |
required |
device |
"phone" | "tablet" | "laptop" | "screen" | "none" | null |
required |
hasScreenshot |
boolean |
required |
reply |
string | null |
required |
repliedAt |
string (date-time) | null |
required |
from |
object | null |
required |
projectId |
string |
required · not empty |
appName |
string | null |
required |
screenshot |
object | null |
required |
screenshotNote |
"removed" | "no-answer" | "timeout" | "blocked" | "tainted" | "too-large" | "failed" | null |
required |
viewer |
object | null |
required |
thread |
object[] |
required |
Room setup
The next steps a room offers, the workspace’s brand, and your own community profile.
getNextSteps
GET /api/projects/:projectId/next-steps
The next steps the project’s room offers at the end of a visit, as you set them, whether the plan lets you choose, and what the room offers now. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
steps |
object[] |
required · at most 6 items |
removed |
object[] |
required |
planAllows |
boolean |
required |
offered |
"meeting" | "yes" | "later" | "colleague" | "question" | "no"[] |
required |
setNextSteps
POST /api/projects/:projectId/next-steps
Sets which next steps the room offers, in what order and in what words. A step left out of steps is deleted: never offered, its words kept in removed; sending it again adds it back. On a plan that cannot choose, the setting is kept, and the room offers only a question.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
steps |
object[] |
required · at most 6 items |
Reply: object
| Field | Type | |
|---|---|---|
steps |
object[] |
required · at most 6 items |
removed |
object[] |
required |
planAllows |
boolean |
required |
offered |
"meeting" | "yes" | "later" | "colleague" | "question" | "no"[] |
required |
getBrand
GET /api/brand
Your workspace’s brand: its name, accent colour and logo, and whether the plan shows it in the room. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
name |
string | null |
required |
accent |
string | null |
required |
logo |
object | null |
required |
workspaceName |
string |
required |
planAllows |
boolean |
required |
logoAllows |
boolean |
required |
problems |
object[] |
optional |
setBrand
POST /api/brand
Sets the brand’s name and accent colour (#rrggbb); null clears either. On a plan without its own branding, rooms carry “Made with Roomi” instead. An accent a viewer could not read in the room is refused with 400, reason: contrast, and problems saying each pair that fails and a shade that would pass. The logo is uploaded with PUT /api/brand/logo: a PNG, JPEG or WebP image of up to 256 KB, from 16 × 16 to 2048 × 2048 pixels, and no more than 8 times as wide as it is tall.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
name |
string | null |
required |
accent |
string | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
name |
string | null |
required |
accent |
string | null |
required |
logo |
object | null |
required |
workspaceName |
string |
required |
planAllows |
boolean |
required |
logoAllows |
boolean |
required |
problems |
object[] |
optional |
removeLogo
POST /api/brand/logo/remove
Removes the brand’s logo.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
name |
string | null |
required |
accent |
string | null |
required |
logo |
object | null |
required |
workspaceName |
string |
required |
planAllows |
boolean |
required |
logoAllows |
boolean |
required |
problems |
object[] |
optional |
getTheme
GET /api/brand/theme
Your workspace’s room theme: its tokens as saved (null for none), whether the plan shows it, the first plan that does, every colour and value the room draws for it with your accent, and anything in it a viewer could not read now. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
theme |
object | null |
required |
planAllows |
boolean |
required |
shownOn |
string | null |
required |
effective |
{ [key]: string } |
required |
problems |
object[] |
required |
fellBack |
string[] |
required |
setTheme
POST /api/brand/theme
Saves the room theme whole: a token left out is the room’s own. Colours are #rrggbb; radius is square, soft or round; font is system, serif or rounded. A theme a viewer could not read is refused with 400, reason: contrast, and its problems. Kept whatever the plan, and shown on a plan that includes it.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
theme |
object |
required |
Reply: object
| Field | Type | |
|---|---|---|
theme |
object | null |
required |
planAllows |
boolean |
required |
shownOn |
string | null |
required |
effective |
{ [key]: string } |
required |
problems |
object[] |
required |
fellBack |
string[] |
required |
resetTheme
POST /api/brand/theme/reset
Removes the room theme: rooms are drawn in the room’s own look again.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
theme |
object | null |
required |
planAllows |
boolean |
required |
shownOn |
string | null |
required |
effective |
{ [key]: string } |
required |
problems |
object[] |
required |
fellBack |
string[] |
required |
checkTheme
POST /api/brand/theme/check
Checks a room theme, with another accent if you give one, and says what the room would draw and what would be refused. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
theme |
object |
required |
accent |
string | null |
optional |
Reply: object
| Field | Type | |
|---|---|---|
problems |
object[] |
required |
effective |
{ [key]: string } |
required |
listThemePresets
GET /api/brand/theme/presets
The room theme presets: the built-in ones every workspace has (ids starting builtin:), each passing every contrast check, then your workspace’s own, by name. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
presets |
object[] |
required |
saveThemePreset
POST /api/brand/theme/presets
Keeps a room theme under a name (up to 60 characters, unique in the workspace whatever its case): 409 when it is taken. A theme a viewer could not read is refused with 400, reason: contrast, and its problems. A workspace keeps up to 50.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–60 characters |
theme |
object |
required |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required |
name |
string |
required |
theme |
object |
required |
builtIn |
boolean |
required |
renameThemePreset
POST /api/brand/theme/presets/:presetId/rename
Gives one of your workspace’s presets a new name. A built-in one keeps its own.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: presetId
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–60 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required |
name |
string |
required |
theme |
object |
required |
builtIn |
boolean |
required |
deleteThemePreset
POST /api/brand/theme/presets/:presetId/delete
Deletes one of your workspace’s presets. The room theme is not touched.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: presetId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
presets |
object[] |
required |
applyThemePreset
POST /api/brand/theme/presets/:presetId/apply
Saves a preset as the room theme, checked as POST /api/brand/theme checks one. A preset another workspace kept is 404, as an unknown id is.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: presetId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
theme |
object | null |
required |
planAllows |
boolean |
required |
shownOn |
string | null |
required |
effective |
{ [key]: string } |
required |
problems |
object[] |
required |
fellBack |
string[] |
required |
getProfile
GET /api/me/profile
Your own community handle and bio. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
handle |
string | null |
required |
bio |
string | null |
required |
setProfile
POST /api/me/profile
Sets your community handle and bio. The handle follows a project address’s rules and is unique among people: refused as format, reserved, impersonation, banned or taken.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
handle |
string |
required · 3–40 characters |
bio |
string | null |
required |
Reply: object
| Field | Type | |
|---|---|---|
handle |
string | null |
required |
bio |
string | null |
required |
The community
A project’s community card, listing and unlisting it, the room’s access rule, and the one-time passes into a room.
getCard
GET /api/projects/:projectId/card
The project’s community card: its title, line and cover, where its listing stands (draft, listed, blocked with what a check found, pulled with Roomi's comment, or pending while it waits for review), whether a new cover is still held back, whether a review can be asked for, the public address it would have, and whether suggested wording is available. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
saveCard
POST /api/projects/:projectId/card
Saves the card’s title and line. A listed card’s new words are checked first: it stays listed if they pass, and is blocked (off the community) if a check fails. At most 10 such edits a day; past that, 429. Any other card keeps its state. The cover is uploaded with PUT /api/projects/:projectId/card/cover: a PNG, JPEG or WebP image of up to 1 MB, once the card exists; a new cover is held back from the community until its own check passes.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
title |
string |
required · 1–60 characters |
line |
string |
required · 1–140 characters |
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
removeCover
POST /api/projects/:projectId/card/cover/remove
Removes the card’s cover.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
checkBuildCover
POST /api/projects/:projectId/card/cover/build/check
Reads an image in the project’s live build, by its path from the build’s root, as the card’s cover would take it, and returns its type and size in bytes. The type is read from the file’s bytes, never its name: a PNG, JPEG or WebP image, at most 1 MB, or it is refused as file. A container build is never unpacked, so its files are refused too. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
path |
string |
required · 1–255 characters |
Reply: object
| Field | Type | |
|---|---|---|
path |
string |
required |
type |
"image/png" | "image/jpeg" | "image/webp" |
required |
bytes |
integer |
required |
coverFromBuild
POST /api/projects/:projectId/card/cover/build
Makes an image in the project’s live build the card’s cover, checked as checkBuildCover checks it, and copied on the platform: nothing is uploaded, and the cover is stored and served from the card’s row like an uploaded one. Needs a saved card. Held back from the community until its own check passes, as with an upload.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
path |
string |
required · 1–255 characters |
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
listProject
POST /api/projects/:projectId/card/list
Lists the project on the community: runs the pre-flight scan, which warns and never blocks, and Roomi's checks. If they pass it is listed at once; if one fails it is blocked, with the part and the reason. After Roomi took it off before, it waits for review (pending). Refused as unfinished without a card or without a live build; at most 3 a day for a workspace, 429 past that.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
rehearseListing
GET /api/projects/:projectId/card/listing
What asking to list would do now — listed, blocked with its findings, pending, already or refused — and why, with the pre-flight warnings. Runs the checks without the content classifier, and writes and counts nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
outcome |
"listed" | "blocked" | "pending" | "already" | "refused" |
required |
findings |
object[] |
required |
warnings |
object[] |
required |
said |
string[] |
required |
appealListing
POST /api/projects/:projectId/card/appeal
Asks Roomi to review a block or a decision to take the listing off, in your own words (10 to 1,000 characters). One open at a time, at most 3 a workspace in 30 days: 409 while one is open, 429 past the limit. If it is upheld, exactly this card and build are listed.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
message |
string |
required · 10–1000 characters |
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
listNotices
GET /api/notices
Your own notices in this workspace, newest first, the last fifty: a listing taken off, a project taken down, a review decided. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
kind |
"listing.blocked" | "listing.pulled" | "listing.unlisted" | "listing.takedown" | "appeal.upheld" | "appeal.denied" | "plans.open" | "viewer.opened" | "viewer.returned" | "viewer.wrote" | "viewer.yes" | "meeting.booked" | "meeting.cancelled" | "feedback.replied" | "summary.weekly" | "project.moved" | "plan.granted" | "plan.grant-ending" | "plan.grant-ended" |
required |
title |
string |
required |
body |
string |
required |
href |
string | null |
required |
createdAt |
string (date-time) |
required |
readAt |
string (date-time) | null |
required |
readNotices
POST /api/notices/read
Marks your own notices read: the ids given, or all of them. Says how many changed.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
ids |
string[] |
optional · at most 50 items |
Reply: object
| Field | Type | |
|---|---|---|
read |
integer |
required |
scanCard
POST /api/projects/:projectId/card/scan
Runs the pre-flight scan on the project with the title and line given, as asking to list would, and returns its warnings. Changes nothing: the card is not saved and nothing is listed. The Claude connector’s set_community_card and request_listing show it before you agree.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
title |
string |
required · 1–60 characters |
line |
string |
required · 1–140 characters |
Reply: object
| Field | Type | |
|---|---|---|
warnings |
object[] |
required |
unlistProject
POST /api/projects/:projectId/card/unlist
Takes the project off the community at once; its public address stops answering. The card is kept as a draft.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
projectId |
string |
required · not empty |
title |
string |
required |
line |
string |
required |
cover |
object | null |
required |
status |
"draft" | "listed" | "blocked" | "pulled" | "pending" |
required |
rejectReason |
string | null |
required |
submittedAt |
string (date-time) | null |
required |
reviewedAt |
string (date-time) | null |
required |
warnings |
object[] |
required |
blocked |
object[] |
required |
coverPending |
boolean |
required |
hidden |
boolean |
required |
appealable |
boolean |
required |
appeal |
object | null |
required |
publicUrl |
string (uri) |
required |
suggest |
boolean |
optional |
updatedAt |
string (date-time) | null |
required |
previewPass
POST /api/projects/:projectId/preview
A one-time address that opens the room exactly as a viewer sees it, marked as a preview, recording nothing. For a member of the project’s workspace; it lives 120 seconds and is spent on arrival.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
getAccess
GET /api/projects/:projectId/access
Whether the project’s private links ask for an email before the room shows anything, and whether the plan has private links at all. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
requireEmail |
boolean |
required |
privateLinks |
boolean |
required |
immersive |
object |
optional |
setAccess
POST /api/projects/:projectId/access
Sets whether the project’s private links ask the viewer for an email before the room shows anything. Nothing is sent to the email, and it is not verified.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: object
| Field | Type | |
|---|---|---|
requireEmail |
boolean |
required |
Reply: object
| Field | Type | |
|---|---|---|
requireEmail |
boolean |
required |
privateLinks |
boolean |
required |
immersive |
object |
optional |
communityPass
POST /api/community/pass
A one-time address back into a listed project’s room, signed in, to comment or react. Any signed-in person may ask, for any listed project; the room learns their public face and nothing else. A project that is not listed is 404.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
slug |
string |
required · 1–63 characters |
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
Arranging projects
Your workspace’s own order and groups of projects, as the app’s side bar and Projects page draw them, and where each project stands on the community. Cosmetic: nothing here changes who can see a project.
getArrangement
GET /api/arrangement
Your workspace’s groups in order, and every project once, in the order it is drawn: the ungrouped first, then each group’s. A project nobody has placed yet comes first, newest first. Each says where it stands on the community: unlisted, listed, blocked (a check kept it off), pulled (taken off) or pending (waiting for review). Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
groups |
object[] |
required |
projects |
object[] |
required |
arrangeProjects
POST /api/arrangement
Sets the order: the ungrouped projects, then each group with its projects, groups in the order given. What is left out keeps its place after what was given. Each id at most once (422 otherwise); a project or group not your workspace’s is 404, and nothing moves.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
ungrouped |
string[] |
required · at most 500 items |
groups |
object[] |
required · at most 30 items |
Reply: object
| Field | Type | |
|---|---|---|
groups |
object[] |
required |
projects |
object[] |
required |
createGroup
POST /api/groups
Adds an empty group, last. Its name is 1 to 40 characters; a workspace has at most 30 groups.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–40 characters |
Reply: object
| Field | Type | |
|---|---|---|
groups |
object[] |
required |
projects |
object[] |
required |
renameGroup
POST /api/groups/:groupId
Renames one group. Another workspace’s group is 404.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: groupId
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–40 characters |
Reply: object
| Field | Type | |
|---|---|---|
groups |
object[] |
required |
projects |
object[] |
required |
deleteGroup
POST /api/groups/:groupId/delete
Deletes one group and nothing else: its projects move to the end of the ungrouped. Another workspace’s group is 404.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: groupId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
groups |
object[] |
required |
projects |
object[] |
required |
Public
Answers anyone, signed in or not, and shows only what is listed on the community.
profile
GET /api/community/people/:handle
A publisher’s public page, by handle: their name, avatar and bio, and their projects listed on the community. A handle nobody has is 404.
Open to anyone, signed in or not.
Path parameters: handle
Body: none
Reply: object
| Field | Type | |
|---|---|---|
handle |
string |
required |
name |
string |
required |
bio |
string | null |
required |
image |
string (uri) | null |
required |
projects |
object[] |
required |
listings
GET /api/community/listings
Every project listed on the community, newest listing first: each card’s title and line, its public address, and whether it has a cover (at /api/community/projects/:slug/cover). Nothing about who built it: no name, handle, avatar or email. Cached for a minute; getroomi.com may read it from a browser.
Open to anyone, signed in or not.
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
slug |
string |
required |
title |
string |
required |
line |
string |
required |
url |
string (uri) |
required |
cover |
boolean |
required |
listedAt |
string (date-time) |
required |
credit |
string | null |
optional |
type |
"static" | "container" | "immersive" |
optional |
Plan and usage
The workspace’s plan, and what it has used this month.
getBilling
GET /api/billing
Your workspace’s plan and its status, its seats, this month’s usage, the viewer-hours allowance and where it stands, and whether the workspace is suspended. Also whether paid plans are open (paidPlans), whether you may manage billing and see invoices, a change waiting for the period’s end, and any payment not made: its stage (grace, frozen, free), what is owed, and the dates it freezes, moves to Free and is written off (lifecycle). Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
plan |
"free" | "pro" | "team" | "organisation" | "solo" | "studio" | "agency" | "enterprise" |
required |
kind |
"personal" | "team" |
optional |
seats |
object |
optional |
interval |
"month" | "year" | null |
required |
status |
"active" | "past_due" | "canceled" |
required |
currentPeriodEnd |
string (date-time) | null |
required |
usage |
object |
required |
allowance |
object |
required |
history |
object |
optional |
suspended |
boolean |
required |
paidPlans |
"off" | "open" |
required |
immersive |
boolean |
optional |
canManage |
boolean |
optional |
canSeeInvoices |
boolean |
optional |
subscribed |
boolean |
optional |
cancelAtPeriodEnd |
boolean |
optional |
selected |
object | null |
optional |
grace |
object | null |
optional |
frozen |
boolean |
optional |
lifecycle |
object | null |
optional |
projectBounces
GET /api/projects/:projectId/bounces
How many viewers a full room turned away from the project this calendar month (UTC), counted once per session per hour. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: projectId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
thisMonth |
integer |
required |
billingCheckout
POST /api/billing/checkout
Stripe’s hosted Checkout for a paid plan (pro, or team with seats from 2 to 5, by month or year): the address to send the person to. VAT is added by Stripe Tax from the billing address; a VAT number can be given. It grants nothing: the plan changes when Stripe confirms the payment. A team’s owners only, or the person in their own workspace (403 otherwise). Refused with 422 for a plan the workspace’s kind does not hold (Team for a person, Pro for a team), for seats outside the plan’s (a sixth is Enterprise, by arrangement: contact sales), for a workspace that already pays or still owes for a plan it lost.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
plan |
"pro" | "team" |
required |
interval |
"month" | "year" |
required |
seats |
integer |
optional · at most 1000 |
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
billingPortal
POST /api/billing/portal
Stripe’s customer portal for the workspace: the card, the billing address and VAT number, and cancelling at the period’s end. Plans and seats are changed with POST /api/billing/plan, not there. After a failed payment it opens on updating the card. Owners only; 422 until the workspace has paid for something. Open while the workspace is frozen.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
billingChangePlan
POST /api/billing/plan
Changes a paid subscription’s billing period or a team’s seats. Without commit: true it is a rehearsal and changes nothing: it says whether the change is an upgrade or a downgrade, what an upgrade charges now, when a downgrade lands, which projects would pause, and why it would be refused. More seats, or a month to a year, take effect at once, invoiced with proration, and keep what it had until it is paid (payUrl is Stripe’s page for a payment that needs the person). Fewer seats, or a year to a month, wait for the period’s end and refund nothing; choosing what it has again drops the change. More of one and less of the other is refused (mixed): one at a time. Seats the team’s people do not fit, and a sixth seat, are refused. Owners only, and not while a payment is owed.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
plan |
"pro" | "team" |
required |
interval |
"month" | "year" |
required |
seats |
integer |
optional · at most 1000 |
commit |
boolean |
optional |
Reply: object
| Field | Type | |
|---|---|---|
committed |
boolean |
required |
direction |
"upgrade" | "downgrade" | "same" | "mixed" |
required |
from |
object |
required |
to |
object |
required |
takesEffect |
"now" | "period-end" |
required |
at |
string (date-time) | null |
required |
amountDuePence |
integer | null |
required |
pauses |
string[] |
required |
refusals |
string[] |
required |
payUrl |
string (uri) | null |
required |
detail |
string |
required |
billingChooseFree
POST /api/billing/free
While a payment is owed, moves the workspace to Free now: the subscription is cancelled in Stripe, nothing is refunded, its most recently used projects keep running, and what it had is not kept. What is owed stays owed until it is paid, and no paid plan can be chosen until then. Without commit: true it is a rehearsal and names the projects that would pause. Owners only; open while the workspace is frozen.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
commit |
boolean |
optional |
Reply: object
| Field | Type | |
|---|---|---|
committed |
boolean |
required |
refusals |
string[] |
required |
pauses |
string[] |
required |
running |
integer | null |
required |
detail |
string |
required |
billingRestore
POST /api/billing/restore
After a workspace moved to Free for a payment not made, and that payment is now paid: Stripe’s Checkout for the plan it had, at the seats and billing period it had. Once paid, everything comes back, the projects that ran before first. Owners only.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
url |
string (uri) |
required |
listInvoices
GET /api/billing/invoices
Every invoice and receipt the workspace has had, newest first: its number, date, period, total, VAT, status, any refund, and whether it is still owed. No links: ask POST /api/billing/invoices/{invoiceId}/link for one. Owners only (403 otherwise); open while the workspace is frozen. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
number |
string | null |
required |
status |
"paid" | "open" | "failed" | "void" |
required |
createdAt |
string (date-time) |
required |
periodStart |
string (date-time) | null |
required |
periodEnd |
string (date-time) | null |
required |
subtotalPence |
integer | null |
required |
taxPence |
integer | null |
required |
totalPence |
integer |
required |
refundedPence |
integer |
required |
currency |
string | null |
required |
owed |
boolean |
required |
invoiceLink
POST /api/billing/invoices/:invoiceId/link
Links to one invoice, asked of Stripe each time and never kept, since they expire: its PDF, and its page on Stripe, where an open invoice is paid and a paid one’s receipt is downloaded. Owners only; another workspace’s invoice is 404. Open while the workspace is frozen. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: invoiceId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
pdfUrl |
string (uri) | null |
required |
pageUrl |
string (uri) | null |
required |
owed |
boolean |
required |
You, and your workspace’s people
Your name and photo as the app draws you, how you sign in and where you are signed in, deleting your account, and your workspace’s people and container demos. Nothing here names anyone else to change.
whoami
GET /api/me/account
Who you are, as the app draws you: your name (or your email while you have set none), your picture — your uploaded photo, else your sign-in provider’s avatar, else none — and the workspace your session is in, with your role. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
name |
string |
required |
displayName |
string |
required |
nameChosen |
boolean |
optional |
suggestedName |
string |
optional |
email |
string |
required |
emailVerified |
boolean |
required |
image |
string | null |
required |
photo |
object | null |
required |
providerImage |
boolean |
required |
handle |
string | null |
required |
workspace |
object |
required |
createdAt |
string (date-time) |
required |
setName
POST /api/me/name
Sets the name you are shown by, to you and to the people in your workspace: 1 to 80 characters.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–80 characters |
Reply: object
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
name |
string |
required |
displayName |
string |
required |
nameChosen |
boolean |
optional |
suggestedName |
string |
optional |
email |
string |
required |
emailVerified |
boolean |
required |
image |
string | null |
required |
photo |
object | null |
required |
providerImage |
boolean |
required |
handle |
string | null |
required |
workspace |
object |
required |
createdAt |
string (date-time) |
required |
removePhoto
POST /api/me/photo/remove
Removes your uploaded photo; you are drawn with your provider’s avatar, or your initials. A photo is uploaded with PUT /api/me/photo: a PNG, JPEG or WebP image of up to 2 MB and 4096 pixels a side, checked by its own bytes.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
name |
string |
required |
displayName |
string |
required |
nameChosen |
boolean |
optional |
suggestedName |
string |
optional |
email |
string |
required |
emailVerified |
boolean |
required |
image |
string | null |
required |
photo |
object | null |
required |
providerImage |
boolean |
required |
handle |
string | null |
required |
workspace |
object |
required |
createdAt |
string (date-time) |
required |
deletable
GET /api/me/deletable
Whether your account can be deleted now, and what stands in the way: a workspace you own that still holds projects or other people. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
allowed |
boolean |
required |
blockers |
object[] |
required |
deleteAccount
POST /api/me/delete
Deletes your account: your sign-in methods, passkeys and sessions, your profile and photo, and every workspace you own. confirm must be your email. Refused with 422 while deletable names a workspace.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
confirm |
string |
required |
Reply: object
| Field | Type | |
|---|---|---|
deleted |
true |
required |
containerUsage
GET /api/usage/containers
Your workspace’s container demos this calendar month (UTC): runs, container-hours, starts that failed, viewers held back at the plan’s cap, and the median start. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
month |
string |
required |
runs |
integer |
required |
containerHours |
number |
required |
failedStarts |
integer |
required |
heldBack |
integer |
required |
medianColdStartMs |
integer | null |
required |
members
GET /api/workspace/people
The people in your workspace, each with the name and picture the app draws them with. Their photos are served at GET /api/people/:userId/photo to people in a workspace with them, and to nobody else. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
userId |
string |
required · not empty |
displayName |
string |
required |
image |
string | null |
required |
signIns
GET /api/me/sign-in
How you can sign in: GitHub and Google, each set up on the platform or not and linked to you or not, how many passkeys you have, and whether emailed links are offered. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
providers |
object[] |
required |
passkeys |
integer |
required |
magicLinks |
boolean |
required |
disconnect
POST /api/me/sign-in/:provider/disconnect
Unlinks GitHub or Google from your account. Refused with 422 while it is your only way in: no other provider, and no passkey.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: provider
Body: none
Reply: object
| Field | Type | |
|---|---|---|
providers |
object[] |
required |
passkeys |
integer |
required |
magicLinks |
boolean |
required |
sessions
GET /api/me/sessions
Every live session of yours, newest first, with the one asking marked current. Each has an id to sign it out by, never the token a cookie carries. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
current |
boolean |
required |
signInMethod |
string | null |
required |
userAgent |
string | null |
required |
device |
string |
required |
createdAt |
string (date-time) |
required |
expiresAt |
string (date-time) |
required |
revokeSession
POST /api/me/sessions/:sessionId/revoke
Signs out one of your sessions. Another person’s session is a 404, and nothing changes.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: sessionId
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
current |
boolean |
required |
signInMethod |
string | null |
required |
userAgent |
string | null |
required |
device |
string |
required |
createdAt |
string (date-time) |
required |
expiresAt |
string (date-time) |
required |
signOutEverywhere
POST /api/me/sessions/revoke-all
Signs out every session of yours, the one asking included.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
signedOut |
integer |
required |
Your first days
The welcome letter, whether you have read it, and a note to the Roomi team from inside the app. Each answers only for the person signed in.
myPreferences
GET /api/me/preferences
Your own preferences: whether you have read the welcome letter and whether the feedback tab is folded. Someone with none yet gets the defaults. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
welcomeSeenAt |
string (date-time) | null |
required |
feedbackTabFolded |
boolean |
required |
welcomeSeen
POST /api/me/welcome/seen
Marks the welcome letter as read, the first time only; calling it again changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
welcomeSeenAt |
string (date-time) | null |
required |
feedbackTabFolded |
boolean |
required |
foldFeedbackTab
POST /api/me/feedback-tab
Folds the “Help us improve” button to a small tab, or opens it out again. Yours alone.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
folded |
boolean |
required |
Reply: object
| Field | Type | |
|---|---|---|
welcomeSeenAt |
string (date-time) | null |
required |
feedbackTabFolded |
boolean |
required |
myOnboarding
GET /api/me/onboarding
Your first run: what you chose on it (on your own or with a team, the plan you want, whether you have left the set-up or hidden its checklist, and where you are in the app’s tour), and the facts it is read from, of the workspace you are signed in to: a connection from Claude or the CLI, a project, a viewer link or a listing, a visit. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
use |
"solo" | "team" | null |
required |
planIntent |
"free" | "pro" | "team" | "organisation" | null |
required |
flowLeftAt |
string (date-time) | null |
required |
checklistDismissedAt |
string (date-time) | null |
required |
tour |
object |
required |
facts |
object |
required |
setOnboarding
POST /api/me/onboarding
Saves what you chose on the first run: any of use, planIntent (one of the plans’ ids; anything else is 400), flowLeft and checklistDismissed. A field left out is kept, and the first time you left the set-up stands. Yours alone: the body cannot name a workspace.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
use |
"solo" | "team" |
optional |
planIntent |
"free" | "pro" | "team" | "organisation" |
optional |
flowLeft |
true |
optional |
checklistDismissed |
boolean |
optional |
Reply: object
| Field | Type | |
|---|---|---|
use |
"solo" | "team" | null |
required |
planIntent |
"free" | "pro" | "team" | "organisation" | null |
required |
flowLeftAt |
string (date-time) | null |
required |
checklistDismissedAt |
string (date-time) | null |
required |
tour |
object |
required |
facts |
object |
required |
setTour
POST /api/me/onboarding/tour
Saves where you are in the app’s tour: step, the stop on show (one of projects, room, links, activity, pipeline and claude), and ended, finished or skipped. The first time you were shown it stands; a stop after an end clears the end. Yours alone, on every device; nothing about it is kept in the browser.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
step |
"projects" | "room" | "links" | "activity" | "pipeline" | "claude" |
optional |
ended |
"finished" | "skipped" |
optional |
Reply: object
| Field | Type | |
|---|---|---|
use |
"solo" | "team" | null |
required |
planIntent |
"free" | "pro" | "team" | "organisation" | null |
required |
flowLeftAt |
string (date-time) | null |
required |
checklistDismissedAt |
string (date-time) | null |
required |
tour |
object |
required |
facts |
object |
required |
sendProductFeedback
POST /api/product-feedback
A note to the Roomi team, filed under you and the workspace you are signed in to, whatever the body says. Up to 2,000 characters, and a few an hour; past that, 429. Says back only that it arrived.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
body |
string |
required · 1–2000 characters |
page |
string |
optional · at most 300 characters |
appVersion |
string |
optional · at most 64 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
createdAt |
string (date-time) |
required |
Notifications
What you hear about, in the app and by email, and your notes to the Roomi team with our replies. Each answers only for the person signed in; the notices themselves are under The community.
myNotificationPreferences
GET /api/me/notifications
What you hear about: for each kind (a viewer opens a link for the first time, comments or asks a question, says yes, a meeting booked or cancelled, a reply to your note), whether it shows in the app and whether it is emailed, as you chose it or by default. With whether the platform sends email yet, and whether your address unsubscribed. Yours alone, in every workspace. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
settings |
object[] |
required |
emailOn |
boolean |
required |
unsubscribed |
boolean |
required |
setNotificationPreference
POST /api/me/notifications
Turns one kind on or off on one channel, app or email, for you alone, and answers with every setting. Only the kinds listed can be set: sign-in, security, billing and listing emails are always sent, and asking for one is 400.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
kind |
"viewer.opened" | "viewer.returned" | "viewer.wrote" | "viewer.yes" | "meeting.booked" | "meeting.cancelled" | "feedback.replied" | "summary.weekly" | "project.moved" |
required |
channel |
"app" | "email" |
required |
enabled |
boolean |
required |
Reply: object
| Field | Type | |
|---|---|---|
settings |
object[] |
required |
emailOn |
boolean |
required |
unsubscribed |
boolean |
required |
resubscribe
POST /api/me/notifications/resubscribe
Turns optional email back on for your own address after you followed an unsubscribe link in one. Only an unsubscribe of yours is undone; an address that bounced stays as it is.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object
| Field | Type | |
|---|---|---|
settings |
object[] |
required |
emailOn |
boolean |
required |
unsubscribed |
boolean |
required |
myNotes
GET /api/me/notes
Your notes to the Roomi team, newest first, each with the conversation since: your answers and the team’s replies, signed by Roomi. Only your own. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
body |
string |
required |
page |
string |
required |
createdAt |
string (date-time) |
required |
replied |
boolean |
required |
messages |
object[] |
required |
replyOnNote
POST /api/me/notes/:noteId/replies
Your answer on one of your own notes, up to 2,000 characters: it joins the conversation and the team sees the note again. Someone else’s note is 404, as one that does not exist; past a few answers an hour, 429.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: noteId
Body: object
| Field | Type | |
|---|---|---|
body |
string |
required · 1–2000 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
body |
string |
required |
page |
string |
required |
createdAt |
string (date-time) |
required |
replied |
boolean |
required |
messages |
object[] |
required |
Reports
Reporting a project to Roomi.
reportProject
POST /api/reports
Reports a project, by its address, to Roomi, with a reason and any detail. A project that does not exist is 404; more than 20 reports from one person in 24 hours is 429.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
slug |
string |
required · 1–63 characters |
reason |
"phishing" | "impersonation" | "abuse" | "illegal" | "spam" | "other" |
required |
detail |
string |
optional · at most 1000 characters |
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
API tokens
Your own API tokens in the active workspace, made, listed and revoked signed in. A token cannot reach these: it cannot make or revoke tokens.
listTokens
GET /api/tokens
Your API tokens in the active workspace, newest first, revoked and expired ones included. Never a token itself. Changes nothing.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: none
Reply: object[]
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
name |
string |
required |
createdAt |
string (date-time) |
required |
lastUsedAt |
string (date-time) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
createToken
POST /api/tokens
Makes an API token with a name and, if you give one, an expiry of 1 to 365 days. secret is the token: in this reply once, and never again, since only its hash is kept. Refused as tokens when you already hold 20 live tokens in the workspace.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Body: object
| Field | Type | |
|---|---|---|
name |
string |
required · 1–60 characters |
expiresInDays |
integer |
optional · 1–365 |
Reply: object
| Field | Type | |
|---|---|---|
token |
object |
required |
secret |
string (starts_with) |
required |
revokeToken
POST /api/tokens/:tokenId/revoke
Stops one of your own tokens at once and records who did it. Another person’s token, or one already revoked, is 404.
Signed in: a session cookie (the app) or Authorization: Bearer <token> (the CLI and the connector).
Path parameters: tokenId
Body: none
Reply: object
| Field | Type | |
|---|---|---|
id |
string |
required · not empty |
name |
string |
required |
createdAt |
string (date-time) |
required |
lastUsedAt |
string (date-time) | null |
required |
expiresAt |
string (date-time) | null |
required |
revokedAt |
string (date-time) | null |
required |
Your own domain
A project’s room at an address of yours, on the plans that include it (Your own domain). 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 |