Channels API

Channels are persistent feed containers. All channel operations are under /api/v1/channels.

List Channels

GET /api/v1/channels?workspace_id={workspaceId}

Returns all channels in a workspace with their card counts.

Query Parameters

Parameter	Type	Required	Description
workspace_id	string (UUID)	Yes	The workspace to list channels for

Response

[
  {
    "id": "3f7a1b2c-...",
    "name": "Order Alerts",
    "description": "Real-time order status updates",
    "mode": "view",
    "icon": "📦",
    "workspace_id": "9e4d5f6a-...",
    "created_at": "2025-01-15T10:00:00Z",
    "card_count": 42
  }
]

---

Create Channel

POST /api/v1/channels

Creates a new channel. Counts toward the 50 channels/day limit.

Request Body

Field	Type	Required	Constraints	Default
name	string	Yes	Max 80 characters	—
workspace_id	string (UUID)	Yes	Must be an existing workspace you own	—
description	string	No	Max 300 characters	null
mode	string	No	"view" or "interactive"	"view"
icon	string	No	Single emoji character	"⚡"
webhook_url	string	No	Valid HTTP/HTTPS URL	null
attributes	object	No	Key/value pairs of metadata	{}

Example

curl -X POST /api/v1/channels \
  -H "Authorization: Bearer ofd_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Alerts",
    "workspace_id": "9e4d5f6a-...",
    "description": "Real-time order status updates",
    "mode": "interactive",
    "icon": "📦",
    "webhook_url": "https://your-automation.com/webhook",
    "attributes": {
      "environment": "production",
      "team": "fulfillment"
    }
  }'

Response `201 Created`

{
  "id": "3f7a1b2c-...",
  "name": "Order Alerts",
  "url": "/c/3f7a1b2c-...",
  "workspace_id": "9e4d5f6a-..."
}

---

Get Channel

GET /api/v1/channels/{channelId}

Returns full channel details including header actions.

Response

{
  "id": "3f7a1b2c-...",
  "name": "Order Alerts",
  "description": "Real-time order status updates",
  "mode": "interactive",
  "icon": "📦",
  "webhook_url": "https://your-automation.com/webhook",
  "workspace_id": "9e4d5f6a-...",
  "visibility": "private",
  "created_at": "2025-01-15T10:00:00Z",
  "actions": [
    {
      "id": "a1b2c3d4-...",
      "label": "Refresh",
      "style": "secondary",
      "position": 0
    }
  ]
}

---

Update Channel

PATCH /api/v1/channels/{channelId}

Updates one or more channel fields. Only include fields you want to change.

Request Body

Field	Type	Constraints
name	string	Max 80 characters
description	string	Max 300 characters
mode	string	"view" or "interactive"
icon	string	Single emoji character
webhook_url	string	Valid HTTP/HTTPS URL

Example

curl -X PATCH /api/v1/channels/3f7a1b2c-... \
  -H "Authorization: Bearer ofd_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Alerts (Live)",
    "webhook_url": "https://new-endpoint.com/hook"
  }'

Response `200 OK`

Returns the full updated channel object.

---

Delete Channel

DELETE /api/v1/channels/{channelId}

Permanently deletes a channel and all its cards, actions, attributes, and interaction logs.

Example

curl -X DELETE /api/v1/channels/3f7a1b2c-... \
  -H "Authorization: Bearer ofd_your_key"

Response `200 OK`

{ "deleted": true }

---

Channel Actions

Header actions are buttons displayed at the top of the channel UI. When clicked, they fire an header_action interaction to your webhook.

Add Action

POST /api/v1/channels/{channelId}/actions

Request Body

Field	Type	Required	Values	Default
label	string	Yes	Any text	—
style	string	No	"primary", "secondary", "danger"	"primary"
position	integer	No	Display order (ascending)	0

Example

curl -X POST /api/v1/channels/3f7a1b2c-.../actions \
  -H "Authorization: Bearer ofd_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Mark All Read",
    "style": "secondary",
    "position": 0
  }'

Response `201 Created`

{
  "id": "a1b2c3d4-...",
  "channel_id": "3f7a1b2c-...",
  "label": "Mark All Read",
  "style": "secondary",
  "position": 0
}

List Actions

GET /api/v1/channels/{channelId}/actions

Returns all header actions ordered by position ascending.

Delete Action

Actions can be deleted from the dashboard UI.

---

Channel Fields Reference

Field	Type	Description
id	UUID	Unique channel identifier
name	string	Display name (max 80 chars)
description	string | null	Short description (max 300 chars)
mode	"view" | "interactive"	Whether user interactions are enabled
icon	string	Emoji icon
webhook_url	string | null	URL to receive interaction payloads
workspace_id	UUID | null	Parent workspace
visibility	"private" | "protected" | "public"	Access control level
created_at	ISO 8601 string	Creation timestamp
updated_at	ISO 8601 string	Last update timestamp