Workspaces API
Workspaces, members and roles, and invite links.
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/workspaces
Yours (accepted), oldest first
Response
A list of:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
slug | string | yes | |
name | string | yes | |
role | "owner" | "admin" | "member" | "viewer" | yes |
POST /v1/workspaces
You become owner
Body
| Field | Type | Required | Notes |
|---|---|---|---|
slug | string | yes | |
name | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
slug | string | yes | |
name | string | yes | |
role | "owner" | "admin" | "member" | "viewer" | yes |
GET /v1/workspaces/:slug
Members only (404 otherwise)
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
slug | string | yes | |
name | string | yes | |
role | "owner" | "admin" | "member" | "viewer" | yes | |
members | object[] | yes | |
spaceCount | integer | yes | |
createdAt | number | yes | |
seats | object | no | |
publicPage | boolean | no | |
description | string | null | no | |
topic | string | null | no | |
searchIndexed | boolean | no |
PATCH /v1/workspaces/:slug
Admin+; slug must stay unique; publicPage, description, topic, searchIndexed (400 without the public page): cloudy.page/u/:slug; 409 when the slug is a person's handle
Body
| Field | Type | Required | Notes |
|---|---|---|---|
slug | string | no | |
name | string | no | |
publicPage | boolean | no | |
description | string | null | no | |
topic | string | null | no | |
searchIndexed | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
slug | string | yes | |
name | string | yes | |
role | "owner" | "admin" | "member" | "viewer" | yes |
POST /v1/workspaces/:slug/members
Admin+ invites by handle (pending until accepted); only owners add owners
Body
| Field | Type | Required | Notes |
|---|---|---|---|
handle | string | yes | |
role | "owner" | "admin" | "member" | "viewer" | no (default "member") |
Response: 204, no body
PATCH /v1/workspaces/:slug/members/:handle
Admin+; only owners change owners; keeps >= 1 owner
Body
| Field | Type | Required | Notes |
|---|---|---|---|
role | "owner" | "admin" | "member" | "viewer" | yes |
Response: 204, no body
DELETE /v1/workspaces/:slug/members/:handle
Admin+ (or yourself, to leave); keeps >= 1 owner
Response: 204, no body
GET /v1/workspaces/:slug/invites
Admin+; live invite links (not revoked, expired or used up)
Response
| Field | Type | Required | Notes |
|---|---|---|---|
invites | object[] | yes |
POST /v1/workspaces/:slug/invites
Admin+; the link is returned once (stored hashed); only owners make owner links
Body
| Field | Type | Required | Notes |
|---|---|---|---|
role | "owner" | "admin" | "member" | "viewer" | no (default "member") | |
email | string (email) | no | |
maxUses | integer | null | no | |
expiresInDays | integer | no (default 7) |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
invite | object | yes | |
url | string | yes | |
emailed | boolean | yes |
DELETE /v1/workspaces/:slug/invites/:id
Admin+; turns the link off
Response: 204, no body
GET /v1/workspaces/:slug/domains
Admin+; the workspace's own domains (ai.acme.com), and whether this server can add them
Response
| Field | Type | Required | Notes |
|---|---|---|---|
available | boolean | yes | |
limit | number | null | yes | |
domains | object[] | yes |
POST /v1/workspaces/:slug/domains
Admin+; one on paid plans (PLANS customDomains), more on Enterprise; 409 taken or not set up here
Body
| Field | Type | Required | Notes |
|---|---|---|---|
hostname | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
hostname | string | yes | |
status | "pending" | "live" | "failed" | yes | |
records | object[] | yes | |
error | string | null | yes | |
url | string | yes | |
createdAt | number | yes | |
checkedAt | number | null | yes | |
liveAt | number | null | yes |
POST /v1/workspaces/:slug/domains/:hostname/check
Admin+; checks the DNS record and certificate again: pending, live or failed
Response
| Field | Type | Required | Notes |
|---|---|---|---|
hostname | string | yes | |
status | "pending" | "live" | "failed" | yes | |
records | object[] | yes | |
error | string | null | yes | |
url | string | yes | |
createdAt | number | yes | |
checkedAt | number | null | yes | |
liveAt | number | null | yes |
DELETE /v1/workspaces/:slug/domains/:hostname
Admin+; stops serving it and releases the hostname
Response: 204, no body
POST /v1/workspace-invites/preview
Anyone with the link; 404 unknown, 410 revoked/expired/used up
Body
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
workspace | object | yes | |
role | "owner" | "admin" | "member" | "viewer" | yes | |
invitedBy | object | null | yes | |
memberCount | integer | yes | |
expiresAt | number | yes | |
alreadyMember | boolean | yes | |
email | string | null | yes (default null) | |
wrongAccount | boolean | yes (default false) |
POST /v1/workspace-invites/accept
Signed in; joins with the link's role; 403 past the seat limit or wrong email
Body
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
workspace | object | yes |
POST /v1/workspaces/:slug/accept
Accept your pending invite; 403 past the seat limit
Response: 204, no body
POST /v1/workspaces/:slug/decline
Decline your pending invite
Response: 204, no body
GET /v1/workspaces/:slug/audit
Admin+; newest first: members, invites, billing, sharing, going live
Query
| Field | Type | Required | Notes |
|---|---|---|---|
before | integer | no | |
beforeId | string | no | |
limit | integer | no (default 50) |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
events | object[] | yes | |
next | number | null | yes | |
nextId | string | null | no |
GET /v1/workspaces/:slug/activity
Members; changes to the spaces you can see, newest first, each with canUndo; v=2 adds the folder events
Query
| Field | Type | Required | Notes |
|---|---|---|---|
person | string | no | |
before | integer | no | |
beforeId | string | no | |
limit | integer | no (default 50) | |
v | integer | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
events | object[] | yes | |
next | number | null | yes | |
nextId | string | null | yes |
POST /v1/workspaces/:slug/activity/:id/undo
Does the opposite; 409 when it no longer applies; moving to the Trash and removing a folder: people only
Response
| Field | Type | Required | Notes |
|---|---|---|---|
event | object | yes |
GET /v1/workspaces/:slug/folders
Members; the sidebar's folders, any depth, parents first, each with its path and space count
Response
| Field | Type | Required | Notes |
|---|---|---|---|
folders | object[] | yes |
POST /v1/workspaces/:slug/folders
Members who can edit (agents too); 409 when a sibling has the name
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
parentId | string | null | no | |
description | string | null | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
parentId | string | null | yes | |
name | string | yes | |
description | string | null | yes | |
icon | string | null | no | |
path | string | yes | |
spaces | integer | yes | |
createdAt | number | yes |
GET /v1/workspaces/:slug/rules
Members; the workspace's agent rules (every space gets them). enabled: false and none while the feature is off
Response
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
rules | object[] | yes |
POST /v1/workspaces/:slug/rules
Admins; 409 when the name is taken; 404 while the feature is off
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
when | string | no (default "") | |
do | string | yes | |
skill | string | null | no | |
enabled | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
rules | object[] | yes |
PATCH /v1/workspaces/:slug/rules/:name
Admins
Body
| Field | Type | Required | Notes |
|---|---|---|---|
when | string | no | |
do | string | no | |
skill | string | null | no | |
enabled | boolean | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
rules | object[] | yes |
DELETE /v1/workspaces/:slug/rules/:name
Admins
Response
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
rules | object[] | yes |
PATCH /v1/workspaces/:slug/folders/:id
Members who can edit (agents too); rename, describe, change the icon, or move (parentId; never inside itself)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | no | |
description | string | null | no | |
icon | string | null | no | |
parentId | string | null | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
parentId | string | null | yes | |
name | string | yes | |
description | string | null | yes | |
icon | string | null | no | |
path | string | yes | |
spaces | integer | yes | |
createdAt | number | yes |
DELETE /v1/workspaces/:slug/folders/:id
A person only; what was in it moves up a level; Undo in Activity brings it back
Response: 204, no body
GET /v1/workspaces/:slug/tidy
Members; your own look-alike spaces (to merge) and finished ones (to archive)
Response
| Field | Type | Required | Notes |
|---|---|---|---|
lookAlikes | object[] | yes | |
finished | object[] | yes |
GET /v1/workspaces/:slug/waiting
Members only; open threads you wrote in, were @mentioned in, or on spaces you started, where someone else spoke last; newest first; ?before= pages
Query
| Field | Type | Required | Notes |
|---|---|---|---|
before | integer | no | |
beforeId | string | no | |
limit | integer | no (default 20) |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
threads | object[] | yes | |
total | integer | yes | |
spaces | integer | yes | |
next | number | null | yes | |
nextId | string | null | no |