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 |
PATCH /v1/workspaces/:slug
Admin+; slug must stay unique
Body
| Field | Type | Required | Notes |
|---|---|---|---|
slug | string | no | |
name | string | 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
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 |
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 | |
limit | integer | no (default 50) |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
events | object[] | yes | |
next | number | null | yes |