Channel Attributes

Attributes are user-defined key/value metadata attached to channels. Use them to tag channels with environment names, team names, customer IDs, or any other metadata your automation needs.

Setting Attributes

PUT /api/v1/channels/{channelId}/attributes

Upserts (creates or updates) attributes on a channel. Send a flat JSON object of key/value pairs.

Request Body

{
  "environment": "production",
  "team": "fulfillment",
  "customer_id": "cust_12345",
  "priority": "high"
}

Rules:

• Keys are automatically lowercased
• Values must be strings
• Reserved keys (created_at, updated_at) are forbidden
• Sending a key with an empty string value ("") effectively clears that attribute
• Keys not included in the request are not changed (upsert behavior)

Response `200 OK`

{
  "environment": "production",
  "team": "fulfillment",
  "customer_id": "cust_12345",
  "priority": "high",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T11:00:00Z"
}

Setting Attributes at Channel Creation

You can also set attributes when creating a channel:

{
  "name": "Order Alerts",
  "workspace_id": "...",
  "attributes": {
    "environment": "production",
    "team": "fulfillment"
  }
}

---

Getting Attributes

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

Returns all attributes for the channel as a flat object, including metadata timestamps.

Response

{
  "environment": "production",
  "team": "fulfillment",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T11:00:00Z"
}

---

Workspace-Level Attribute Display

Attributes can be configured at the workspace level to appear in the sidebar or as filter options, making it easy to browse and filter channels by their metadata.

Configure Attribute Display

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

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

Field	Type	Description
key	string	The attribute key to configure
use_as_filter	boolean	Show as a filter button in the workspace sidebar
show_in_sidebar	boolean	Show the attribute value next to channel names

How It Looks

When show_in_sidebar: true, channel list items show the attribute value as a label (e.g., production).

When use_as_filter: true, filter buttons appear above the channel list, letting users click to show only channels with that attribute value.

Get Attribute Settings

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

Returns all configured attribute keys for the workspace:

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

---

Use Cases

Environment Tagging

{
  "environment": "production"
}

Filter all production channels from dev/staging ones.

Customer Channels

Create one channel per customer and tag with their ID:

{
  "customer_id": "cust_12345",
  "plan": "enterprise",
  "region": "us-east"
}

Workflow State

Track what stage a process is in:

{
  "stage": "processing",
  "assigned_to": "alice"
}

Update the attribute when the stage changes:

curl -X PUT /api/v1/channels/{channelId}/attributes \
  -H "Authorization: Bearer ofd_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "complete", "assigned_to": "" }'