Rooms API
Rooms: the shared doc, chat, people, sources and builds.
All paths are relative to the API origin. Send Authorization: Bearer <token> unless a route says otherwise; see the API overview for tokens and errors.
GET /v1/rooms
Rooms you can view; ?workspace=<slug>
Query
| Field | Type | Required | Notes |
|---|---|---|---|
workspace | string | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
rooms | object[] | yes |
POST /v1/rooms
Workspace member; plan room limit (403 past it)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
workspace | string | yes | |
name | string | no | |
prompt | string | no | |
template | string | no | |
invites | object[] | no (default []) |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
icon | string | null | yes | |
description | string | null | yes | |
template | string | null | yes | |
workspace | object | yes | |
role | "owner" | "editor" | "commenter" | "viewer" | yes | |
caps | object | yes | |
linkAccess | "none" | "viewer" | "commenter" | "editor" | yes | |
aiSuggest | boolean | yes | |
latestVersion | integer | yes | |
lastActivity | string | null | yes | |
lastActivityAt | number | null | yes | |
appCount | integer | yes | |
path | string | yes | |
url | string | yes | |
createdAt | number | yes |
GET /v1/rooms/:id
View
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
icon | string | null | yes | |
description | string | null | yes | |
template | string | null | yes | |
workspace | object | yes | |
role | "owner" | "editor" | "commenter" | "viewer" | yes | |
caps | object | yes | |
linkAccess | "none" | "viewer" | "commenter" | "editor" | yes | |
aiSuggest | boolean | yes | |
latestVersion | integer | yes | |
lastActivity | string | null | yes | |
lastActivityAt | number | null | yes | |
appCount | integer | yes | |
path | string | yes | |
url | string | yes | |
createdAt | number | yes |
PATCH /v1/rooms/:id
Manage
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | no | |
icon | string | null | no | |
description | string | null | no | |
linkAccess | "none" | "viewer" | "commenter" | "editor" | no | |
aiSuggest | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
icon | string | null | yes | |
description | string | null | yes | |
template | string | null | yes | |
workspace | object | yes | |
role | "owner" | "editor" | "commenter" | "viewer" | yes | |
caps | object | yes | |
linkAccess | "none" | "viewer" | "commenter" | "editor" | yes | |
aiSuggest | boolean | yes | |
latestVersion | integer | yes | |
lastActivity | string | null | yes | |
lastActivityAt | number | null | yes | |
appCount | integer | yes | |
path | string | yes | |
url | string | yes | |
createdAt | number | yes |
DELETE /v1/rooms/:id
Manage
Response: 204, no body
GET /v1/rooms/:id/markdown
View; every page, for agents and export
Response: text/markdown
POST /v1/rooms/:id/messages/:messageId/report
View, signed in; keeps a copy of the message; 404 unknown message
Body
| Field | Type | Required | Notes |
|---|---|---|---|
reason | string | no |
Response: 204, no body
DELETE /v1/rooms/:id/messages/:messageId
The message's author, or manage; sockets get chat.deleted
Response: 204, no body
POST /v1/rooms/:id/ticket
View; short-lived signed ticket for the WebSocket
Response
| Field | Type | Required | Notes |
|---|---|---|---|
url | string | yes | |
expiresAt | number | yes |
GET /v1/rooms/:id/ws
Yjs doc sync, chat, presence, AI suggestions; access re-checked
Request: ?ticket=
Response: WebSocket (RoomDO)
GET /v1/rooms/:id/people
View; pending invites only for manage
Response
| Field | Type | Required | Notes |
|---|---|---|---|
members | object[] | yes | |
invites | object[] | yes |
POST /v1/rooms/:id/people
Manage; handle adds a member, email makes an invite link
Body
| Field | Type | Required | Notes |
|---|---|---|---|
to | string | yes | |
role | "editor" | "commenter" | "viewer" | no (default "editor") |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
member | object | null | yes | |
invite | object | null | yes |
PATCH /v1/rooms/:id/people/:handle
Manage
Body
| Field | Type | Required | Notes |
|---|---|---|---|
role | "editor" | "commenter" | "viewer" | yes |
Response: 204, no body
DELETE /v1/rooms/:id/people/:handle
Manage, or yourself (leave)
Response: 204, no body
DELETE /v1/rooms/:id/invites/:inviteId
Manage
Response: 204, no body
POST /v1/room-invites/accept
Signed in; token stored hashed, single use
Body
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
roomId | string | yes |
GET /v1/rooms/:id/sources
View
Response
| Field | Type | Required | Notes |
|---|---|---|---|
sources | object[] | yes |
POST /v1/rooms/:id/sources
Comment; MAX_SOURCE_BYTES; bytes in R2, never on the content origin
Request: multipart file
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
contentType | string | yes | |
size | number | yes | |
status | "ready" | "unreadable" | yes | |
summary | string | null | yes | |
extractedChars | number | yes | |
hiddenFromAi | boolean | yes | |
uploadedBy | object | null | yes | |
createdAt | number | yes |
GET /v1/rooms/:id/sources/:sourceId/raw
View
Response: file bytes
PATCH /v1/rooms/:id/sources/:sourceId
Edit; { hiddenFromAi }
Body
| Field | Type | Required | Notes |
|---|---|---|---|
hiddenFromAi | boolean | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
contentType | string | yes | |
size | number | yes | |
status | "ready" | "unreadable" | yes | |
summary | string | null | yes | |
extractedChars | number | yes | |
hiddenFromAi | boolean | yes | |
uploadedBy | object | null | yes | |
createdAt | number | yes |
DELETE /v1/rooms/:id/sources/:sourceId
Edit, or the uploader
Response: 204, no body
POST /v1/rooms/:id/build
Edit; new app, or { appId } to rebuild its preview
Body
| Field | Type | Required | Notes |
|---|---|---|---|
pageId | string | no | |
instructions | string | no | |
appId | string | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
app | object | yes |