Tags

The Tags API lets you create personal tags to organize and bookmark chat messages. Tags are private to each user.

Tag Colors

Tags have RGB color values for display. The API returns both individual RGB components and a hex string.

List Tags

Get all your tags.

GET /v1/tags
Authorization: Bearer {token}

Response:

[
  {
    "id": "123456789",
    "name": "Important",
    "color_r": 255,
    "color_g": 0,
    "color_b": 0,
    "color_hex": "#ff0000",
    "created_at": 1703520000
  },
  {
    "id": "234567890",
    "name": "To Review",
    "color_r": 0,
    "color_g": 128,
    "color_b": 255,
    "color_hex": "#0080ff",
    "created_at": 1703510000
  }
]

Create Tag

Create a new tag.

POST /v1/tags
Authorization: Bearer {token}

{
  "name": "Important",
  "color": {
    "r": 255,
    "g": 0,
    "b": 0
  }
}

Response (201 Created):

{
  "id": "123456789",
  "name": "Important",
  "color_r": 255,
  "color_g": 0,
  "color_b": 0,
  "color_hex": "#ff0000",
  "created_at": 1703520000
}

Get Tag

Get tag details.

GET /v1/tags/{tagID}
Authorization: Bearer {token}

Response:

{
  "id": "123456789",
  "name": "Important",
  "color_r": 255,
  "color_g": 0,
  "color_b": 0,
  "color_hex": "#ff0000",
  "created_at": 1703520000
}

Update Tag

Update tag name or color.

PUT /v1/tags/{tagID}
Authorization: Bearer {token}

{
  "name": "Very Important",
  "color": {
    "r": 255,
    "g": 100,
    "b": 0
  }
}

Response:

{
  "id": "123456789",
  "name": "Very Important",
  "color_r": 255,
  "color_g": 100,
  "color_b": 0,
  "color_hex": "#ff6400",
  "created_at": 1703520000
}

Delete Tag

Delete a tag and all its message associations.

DELETE /v1/tags/{tagID}
Authorization: Bearer {token}

Response: 204 No Content

Message Tagging

List Tagged Messages

Get all messages with a specific tag.

GET /v1/tags/{tagID}/messages?limit=50&before={messageID}
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
limit	50	Max results (1-100)
before	-	Cursor for pagination

Response:

{
  "messages": [
    {
      "channel_id": "111222333",
      "message_id": "444555666",
      "tagged_at": 1703520000
    },
    {
      "channel_id": "111222333",
      "message_id": "333444555",
      "tagged_at": 1703515000
    }
  ],
  "has_more": false
}

Add Tag to Message

Tag a message.

POST /v1/tags/{tagID}/messages
Authorization: Bearer {token}

{
  "channel_id": "111222333",
  "message_id": "444555666"
}

Response (201 Created):

{
  "channel_id": "111222333",
  "message_id": "444555666",
  "tagged_at": 1703520000
}

Requirements:

• You must be a member of the channel
• The message must exist

Error Codes:

Code	Description
TAG_NOT_FOUND	Tag doesn't exist
CHAT_NOT_MEMBER	Not a channel member
CHAT_MESSAGE_NOT_FOUND	Message doesn't exist
MESSAGE_TAG_EXISTS	Already tagged

Remove Tag from Message

Remove a tag from a message.

DELETE /v1/tags/{tagID}/messages/{channelID}/{messageID}
Authorization: Bearer {token}

Response: 204 No Content

Error Codes:

Code	Description
TAG_NOT_FOUND	Tag doesn't exist
MESSAGE_TAG_NOT_FOUND	Message not tagged

List Tags for Message

Get all your tags on a specific message.

GET /v1/channels/{channelID}/messages/{messageID}/tags
Authorization: Bearer {token}

Response:

[
  {
    "id": "123456789",
    "name": "Important",
    "color_r": 255,
    "color_g": 0,
    "color_b": 0,
    "color_hex": "#ff0000",
    "created_at": 1703520000
  }
]

Requirements:

• You must be a member of the channel

Use Cases

Bookmarking Important Messages

// Create a "Bookmarks" tag
const tag = await api.post('/v1/tags', {
  name: 'Bookmarks',
  color: { r: 255, g: 215, b: 0 } // Gold
});

// Tag an important message
await api.post(`/v1/tags/${tag.id}/messages`, {
  channel_id: '111222333',
  message_id: '444555666'
});

// Later, find all bookmarked messages
const bookmarks = await api.get(`/v1/tags/${tag.id}/messages`);

Action Items

// Create a "TODO" tag
const todoTag = await api.post('/v1/tags', {
  name: 'TODO',
  color: { r: 255, g: 100, b: 100 } // Light red
});

// Tag messages that need action
await api.post(`/v1/tags/${todoTag.id}/messages`, {
  channel_id: channelId,
  message_id: messageId
});

// Remove when done
await api.delete(`/v1/tags/${todoTag.id}/messages/${channelId}/${messageId}`);

Privacy

• Tags are completely private to each user
• Other users cannot see your tags
• Only you can see which messages you've tagged