Skip to content
Cloudy docs

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:

FieldTypeRequiredNotes
idstringyes
slugstringyes
namestringyes
role"owner" | "admin" | "member" | "viewer"yes

POST /v1/workspaces

You become owner

Body

FieldTypeRequiredNotes
slugstringyes
namestringyes

Response

FieldTypeRequiredNotes
idstringyes
slugstringyes
namestringyes
role"owner" | "admin" | "member" | "viewer"yes

GET /v1/workspaces/:slug

Members only (404 otherwise)

Response

FieldTypeRequiredNotes
idstringyes
slugstringyes
namestringyes
role"owner" | "admin" | "member" | "viewer"yes
membersobject[]yes
spaceCountintegeryes
createdAtnumberyes
seatsobjectno
publicPagebooleanno
descriptionstring | nullno
topicstring | nullno
searchIndexedbooleanno

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

FieldTypeRequiredNotes
slugstringno
namestringno
publicPagebooleanno
descriptionstring | nullno
topicstring | nullno
searchIndexedbooleanno

Response

FieldTypeRequiredNotes
idstringyes
slugstringyes
namestringyes
role"owner" | "admin" | "member" | "viewer"yes

POST /v1/workspaces/:slug/members

Admin+ invites by handle (pending until accepted); only owners add owners

Body

FieldTypeRequiredNotes
handlestringyes
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

FieldTypeRequiredNotes
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

FieldTypeRequiredNotes
invitesobject[]yes

POST /v1/workspaces/:slug/invites

Admin+; the link is returned once (stored hashed); only owners make owner links

Body

FieldTypeRequiredNotes
role"owner" | "admin" | "member" | "viewer"no (default "member")
emailstring (email)no
maxUsesinteger | nullno
expiresInDaysintegerno (default 7)

Response

FieldTypeRequiredNotes
inviteobjectyes
urlstringyes
emailedbooleanyes

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

FieldTypeRequiredNotes
availablebooleanyes
limitnumber | nullyes
domainsobject[]yes

POST /v1/workspaces/:slug/domains

Admin+; one on paid plans (PLANS customDomains), more on Enterprise; 409 taken or not set up here

Body

FieldTypeRequiredNotes
hostnamestringyes

Response

FieldTypeRequiredNotes
hostnamestringyes
status"pending" | "live" | "failed"yes
recordsobject[]yes
errorstring | nullyes
urlstringyes
createdAtnumberyes
checkedAtnumber | nullyes
liveAtnumber | nullyes

POST /v1/workspaces/:slug/domains/:hostname/check

Admin+; checks the DNS record and certificate again: pending, live or failed

Response

FieldTypeRequiredNotes
hostnamestringyes
status"pending" | "live" | "failed"yes
recordsobject[]yes
errorstring | nullyes
urlstringyes
createdAtnumberyes
checkedAtnumber | nullyes
liveAtnumber | nullyes

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

FieldTypeRequiredNotes
tokenstringyes

Response

FieldTypeRequiredNotes
workspaceobjectyes
role"owner" | "admin" | "member" | "viewer"yes
invitedByobject | nullyes
memberCountintegeryes
expiresAtnumberyes
alreadyMemberbooleanyes
emailstring | nullyes (default null)
wrongAccountbooleanyes (default false)

POST /v1/workspace-invites/accept

Signed in; joins with the link's role; 403 past the seat limit or wrong email

Body

FieldTypeRequiredNotes
tokenstringyes

Response

FieldTypeRequiredNotes
workspaceobjectyes

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

FieldTypeRequiredNotes
beforeintegerno
beforeIdstringno
limitintegerno (default 50)

Response

FieldTypeRequiredNotes
eventsobject[]yes
nextnumber | nullyes
nextIdstring | nullno

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

FieldTypeRequiredNotes
personstringno
beforeintegerno
beforeIdstringno
limitintegerno (default 50)
vintegerno

Response

FieldTypeRequiredNotes
eventsobject[]yes
nextnumber | nullyes
nextIdstring | nullyes

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

FieldTypeRequiredNotes
eventobjectyes

GET /v1/workspaces/:slug/folders

Members; the sidebar's folders, any depth, parents first, each with its path and space count

Response

FieldTypeRequiredNotes
foldersobject[]yes

POST /v1/workspaces/:slug/folders

Members who can edit (agents too); 409 when a sibling has the name

Body

FieldTypeRequiredNotes
namestringyes
parentIdstring | nullno
descriptionstring | nullno

Response

FieldTypeRequiredNotes
idstringyes
parentIdstring | nullyes
namestringyes
descriptionstring | nullyes
iconstring | nullno
pathstringyes
spacesintegeryes
createdAtnumberyes

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

FieldTypeRequiredNotes
enabledbooleanyes
rulesobject[]yes

POST /v1/workspaces/:slug/rules

Admins; 409 when the name is taken; 404 while the feature is off

Body

FieldTypeRequiredNotes
namestringyes
whenstringno (default "")
dostringyes
skillstring | nullno
enabledbooleanno

Response

FieldTypeRequiredNotes
enabledbooleanyes
rulesobject[]yes

PATCH /v1/workspaces/:slug/rules/:name

Admins

Body

FieldTypeRequiredNotes
whenstringno
dostringno
skillstring | nullno
enabledbooleanno

Response

FieldTypeRequiredNotes
enabledbooleanyes
rulesobject[]yes

DELETE /v1/workspaces/:slug/rules/:name

Admins

Response

FieldTypeRequiredNotes
enabledbooleanyes
rulesobject[]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

FieldTypeRequiredNotes
namestringno
descriptionstring | nullno
iconstring | nullno
parentIdstring | nullno

Response

FieldTypeRequiredNotes
idstringyes
parentIdstring | nullyes
namestringyes
descriptionstring | nullyes
iconstring | nullno
pathstringyes
spacesintegeryes
createdAtnumberyes

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

FieldTypeRequiredNotes
lookAlikesobject[]yes
finishedobject[]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

FieldTypeRequiredNotes
beforeintegerno
beforeIdstringno
limitintegerno (default 20)

Response

FieldTypeRequiredNotes
threadsobject[]yes
totalintegeryes
spacesintegeryes
nextnumber | nullyes
nextIdstring | nullno