Workspaces API

Workspaces group related channels together and provide a shared view. Workspace operations require user authentication (dashboard session) — they are not available via API key from external automations.

List Workspaces

GET /api/workspaces

Returns all workspaces owned by the authenticated user.

Response

[
  {
    "id": "9e4d5f6a-...",
    "name": "Production Alerts",
    "slug": "production-alerts",
    "custom_slug": "prod",
    "icon": "🚨",
    "visibility": "private",
    "layout": "sidebar",
    "show_search": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
]

---

Create Workspace

POST /api/workspaces

Creates a new workspace. Limited to 3 workspaces per user.

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
icon	string	No	Single emoji, default "🏢"

A URL slug is auto-generated from the name (e.g. "My Workspace" → "my-workspace"). If the slug already exists, a number is appended.

Response `201 Created`

{
  "id": "9e4d5f6a-...",
  "name": "Production Alerts",
  "slug": "production-alerts",
  "icon": "🚨",
  "user_id": "user-uuid",
  "visibility": "private",
  "layout": "sidebar",
  "show_search": true,
  "created_at": "2025-01-15T10:00:00Z"
}

---

Get Workspace

GET /api/workspaces/{id}

Returns a workspace by ID.

---

Update Workspace

PATCH /api/workspaces/{id}

Updates workspace settings. Only include fields you want to change.

Request Body

Field	Type	Constraints	Default
name	string	Any	—
icon	string	Single emoji	"🏢"
visibility	string	"private", "protected", "public"	"private"
password	string	Required if visibility="protected"	—
layout	string	"list", "sidebar", "tabs", "grid"	"sidebar"
show_search	boolean	true or false	true
custom_slug	string	3–48 chars, lowercase alphanumeric + hyphens, globally unique	null

Layouts

Value	Description
"list"	Simple vertical list of channels
"sidebar"	Sidebar navigation with channel feed
"tabs"	Tab bar across the top for each channel
"grid"	Card grid showing channel previews

Visibility

Value	Access
"private"	Only accessible when logged in as the owner
"protected"	Accessible with a password (/api/channel-unlock)
"public"	Accessible by anyone with the URL

Custom Slug

Set a custom slug to give your workspace a memorable URL:

{ "custom_slug": "my-team" }

The workspace will be accessible at /w/by-slug/my-team.

Rules:

• 3–48 characters
• Lowercase letters, numbers, and hyphens only
• Must be globally unique
• Set to null to remove

Example

curl -X PATCH /api/workspaces/9e4d5f6a-... \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "public",
    "layout": "grid",
    "custom_slug": "my-alerts",
    "show_search": true
  }'

---

Delete Workspace

DELETE /api/workspaces/{id}

Deletes a workspace and all its channels, cards, and associated data. You cannot delete your last workspace.

Response

{ "success": true }

---

Attribute Settings

Workspace attribute settings control how channel attributes (key/value metadata) are displayed across the workspace — whether they show up as sidebar labels and/or filter options.

Get Attribute Settings

GET /api/workspaces/{id}/attribute-settings

Returns all attribute keys discovered across channels in this workspace, with their display settings.

[
  {
    "key": "environment",
    "use_as_filter": true,
    "show_in_sidebar": true
  },
  {
    "key": "team",
    "use_as_filter": false,
    "show_in_sidebar": true
  }
]

Update Attribute Setting

PUT /api/workspaces/{id}/attribute-settings

Upserts the display settings for an attribute key.

Request Body

Field	Type	Required	Description
key	string	Yes	Attribute key name
use_as_filter	boolean	No	Show as filter option in the workspace sidebar
show_in_sidebar	boolean	No	Show the value in the channel list/sidebar

{
  "key": "environment",
  "use_as_filter": true,
  "show_in_sidebar": true
}