Skip to content
Honeycomb Docs

Honeycomb

Base URL: /v1

All endpoints require authentication via Bearer token unless noted otherwise.

Rooms

Section titled “Rooms”

List Rooms

Section titled “List Rooms”
GET /v1/honeycomb/rooms

Returns a paginated list of rooms the authenticated user has access to.

Query Parameters

ParameterTypeRequiredDefaultDescription
category_idstringNo—Filter rooms by category
limitintegerNo20Number of rooms to return (max 50)

Response 200 OK

{
  "rooms": [
    {
      "id": "room_abc123",
      "name": "General Chat",
      "description": "Open discussion for everyone",
      "category_id": "cat_xyz",
      "is_private": false,
      "avatar_url": "https://cdn.example.com/rooms/abc123.png",
      "created_at": "2025-08-15T10:30:00Z",
      "member_count": 42
    }
  ]
}

Create Room

Section titled “Create Room”
POST /v1/honeycomb/rooms

Creates a new room. The authenticated user is automatically added as an admin member.

Request Body

FieldTypeRequiredDescription
namestringYesRoom name
descriptionstringNoRoom description
category_idstringNoCategory to assign the room to
is_privatebooleanNoWhether the room is private

Request Example

{
  "name": "Design Team",
  "description": "UI/UX discussions",
  "category_id": "cat_design",
  "is_private": true
}

Response 201 Created

{
  "room": {
    "id": "room_new456",
    "name": "Design Team",
    "description": "UI/UX discussions",
    "category_id": "cat_design",
    "is_private": true,
    "avatar_url": null,
    "created_at": "2025-09-01T14:00:00Z",
    "owner_id": "user_owner789"
  }
}

Get Room Categories

Section titled “Get Room Categories”
GET /v1/honeycomb/rooms/categories

Returns all available room categories.

Response 200 OK

{
  "categories": [
    {
      "id": "cat_xyz",
      "name": "Gaming",
      "icon": "gamepad"
    },
    {
      "id": "cat_design",
      "name": "Design",
      "icon": "palette"
    }
  ]
}

Get Room Details

Section titled “Get Room Details”
GET /v1/honeycomb/rooms/{id}

Returns the full room object including members (with profiles), the last 50 messages (with author data), and roles.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Response 200 OK

{
  "room": {
    "id": "room_abc123",
    "name": "General Chat",
    "description": "Open discussion for everyone",
    "category_id": "cat_xyz",
    "is_private": false,
    "avatar_url": null,
    "created_at": "2025-08-15T10:30:00Z"
  },
  "members": [
    {
      "user_id": "user_001",
      "role": "admin",
      "joined_at": "2025-08-15T10:30:00Z",
      "profile": {
        "name": "Alice",
        "avatar_url": "https://cdn.example.com/avatars/alice.png",
        "username": "alice"
      }
    }
  ],
  "messages": [
    {
      "id": "msg_100",
      "content": "Hello everyone!",
      "created_at": "2025-09-10T09:15:00Z",
      "author": {
        "id": "user_001",
        "name": "Alice",
        "avatar_url": "https://cdn.example.com/avatars/alice.png"
      }
    }
  ],
  "roles": ["admin", "member"]
}

Update Room

Section titled “Update Room”
PATCH /v1/honeycomb/rooms/{id}

Updates room properties. Only allowed fields are accepted.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
namestringNoRoom name
descriptionstringNoRoom description
category_idstringNoCategory ID
is_privatebooleanNoPrivate flag
avatar_urlstringNoRoom avatar URL

Request Example

{
  "name": "Renamed Room",
  "is_private": false
}

Response 200 OK

{
  "room": {
    "id": "room_abc123",
    "name": "Renamed Room",
    "description": "Open discussion for everyone",
    "category_id": "cat_xyz",
    "is_private": false,
    "avatar_url": null,
    "created_at": "2025-08-15T10:30:00Z"
  }
}

Delete Room

Section titled “Delete Room”
DELETE /v1/honeycomb/rooms/{id}

Permanently deletes a room. Cascades to all messages and member records.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Response 200 OK

{
  "message": "Room deleted successfully"
}

Join Room

Section titled “Join Room”
POST /v1/honeycomb/rooms/{id}/join

Adds the authenticated user to the room with the member role.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Response 200 OK

{
  "member": {
    "user_id": "user_001",
    "room_id": "room_abc123",
    "role": "member",
    "joined_at": "2025-09-12T08:00:00Z"
  }
}

Leave Room

Section titled “Leave Room”
POST /v1/honeycomb/rooms/{id}/leave

Removes the authenticated user from the room.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Response 200 OK

{
  "message": "Left room successfully"
}

List Room Messages

Section titled “List Room Messages”
GET /v1/honeycomb/rooms/{id}/messages

Returns messages in a room using cursor-based pagination.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Query Parameters

ParameterTypeRequiredDefaultDescription
cursorstringNo—Cursor for pagination (message ID)
limitintegerNo50Number of messages to return (max 100)

Response 200 OK

{
  "messages": [
    {
      "id": "msg_200",
      "content": "Hey there!",
      "created_at": "2025-09-12T11:00:00Z",
      "author": {
        "id": "user_002",
        "name": "Bob",
        "avatar_url": "https://cdn.example.com/avatars/bob.png"
      },
      "reactions": [
        { "emoji": "👍", "count": 3 }
      ]
    }
  ],
  "next_cursor": "msg_199"
}

Send Room Message

Section titled “Send Room Message”
POST /v1/honeycomb/rooms/{id}/messages

Sends a message to the specified room.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
contentstringYesMessage content

Request Example

{
  "content": "Hello from the API!"
}

Response 201 Created

{
  "message": {
    "id": "msg_201",
    "content": "Hello from the API!",
    "created_at": "2025-09-12T11:05:00Z",
    "author": {
      "id": "user_001",
      "name": "Alice",
      "avatar_url": "https://cdn.example.com/avatars/alice.png"
    }
  }
}

React to Room Message

Section titled “React to Room Message”
POST /v1/honeycomb/rooms/{id}/messages/{msgId}/reactions

Adds or updates a reaction on a room message. Upserts — if the user already reacted with the same emoji, the reaction is updated.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID
msgIdstringYesMessage ID

Request Body

FieldTypeRequiredDescription
emojistringYesEmoji character

Request Example

{
  "emoji": "🔥"
}

Response 200 OK

{
  "reaction": {
    "message_id": "msg_201",
    "user_id": "user_001",
    "emoji": "🔥"
  }
}

Invite to Room

Section titled “Invite to Room”
POST /v1/honeycomb/rooms/{id}/invite

Invites a user to the room.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
user_idstringYesUser ID to invite

Request Example

{
  "user_id": "user_005"
}

Response 200 OK

{
  "invitation": {
    "room_id": "room_abc123",
    "user_id": "user_005",
    "invited_by": "user_001",
    "created_at": "2025-09-12T12:00:00Z"
  }
}

Manage Roles

Section titled “Manage Roles”
PATCH /v1/honeycomb/rooms/{id}/roles

Updates a member’s role within the room.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
user_idstringYesTarget user ID
rolestringYesNew role (admin or member)

Request Example

{
  "user_id": "user_005",
  "role": "admin"
}

Response 200 OK

{
  "member": {
    "user_id": "user_005",
    "room_id": "room_abc123",
    "role": "admin"
  }
}

Mute User

Section titled “Mute User”
POST /v1/honeycomb/rooms/{id}/moderation/mute

Mutes a user in the room. If duration_minutes is omitted, the mute is indefinite.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
user_idstringYesUser ID to mute
duration_minutesintegerNoMute duration in minutes (indefinite if omitted)

Request Example

{
  "user_id": "user_010",
  "duration_minutes": 30
}

Response 200 OK

{
  "moderation": {
    "action": "mute",
    "user_id": "user_010",
    "room_id": "room_abc123",
    "duration_minutes": 30,
    "expires_at": "2025-09-12T12:30:00Z"
  }
}

Ban User

Section titled “Ban User”
POST /v1/honeycomb/rooms/{id}/moderation/ban

Bans a user from the room by setting the is_banned flag.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
user_idstringYesUser ID to ban

Request Example

{
  "user_id": "user_010"
}

Response 200 OK

{
  "moderation": {
    "action": "ban",
    "user_id": "user_010",
    "room_id": "room_abc123",
    "is_banned": true
  }
}

Kick User

Section titled “Kick User”
POST /v1/honeycomb/rooms/{id}/moderation/kick

Removes a user from the room without banning them.

Path Parameters

ParameterTypeRequiredDescription
idstringYesRoom ID

Request Body

FieldTypeRequiredDescription
user_idstringYesUser ID to kick

Request Example

{
  "user_id": "user_010"
}

Response 200 OK

{
  "moderation": {
    "action": "kick",
    "user_id": "user_010",
    "room_id": "room_abc123"
  }
}

Direct Messages

Section titled “Direct Messages”

List Conversations

Section titled “List Conversations”
GET /v1/honeycomb/dm

Returns all DM conversations for the authenticated user, sorted by most recent activity. Includes the partner’s profile.

Response 200 OK

{
  "conversations": [
    {
      "id": "dm_conv_001",
      "partner": {
        "id": "user_002",
        "name": "Bob",
        "avatar_url": "https://cdn.example.com/avatars/bob.png",
        "username": "bob"
      },
      "last_message": {
        "content": "See you tomorrow!",
        "created_at": "2025-09-12T18:00:00Z"
      },
      "updated_at": "2025-09-12T18:00:00Z"
    }
  ]
}

Start Conversation

Section titled “Start Conversation”
POST /v1/honeycomb/dm

Creates a new DM conversation with a user. If a conversation already exists, returns it with existing: true.

Request Body

FieldTypeRequiredDescription
user_idstringYesUser ID to start DM with

Request Example

{
  "user_id": "user_003"
}

Response 201 Created

{
  "conversation": {
    "id": "dm_conv_002",
    "partner": {
      "id": "user_003",
      "name": "Charlie",
      "avatar_url": "https://cdn.example.com/avatars/charlie.png"
    },
    "created_at": "2025-09-12T19:00:00Z"
  },
  "existing": false
}

Get Conversation Messages

Section titled “Get Conversation Messages”
GET /v1/honeycomb/dm/{id}

Returns messages in a DM conversation using cursor-based pagination. Messages are returned in reverse chronological order for display.

Path Parameters

ParameterTypeRequiredDescription
idstringYesConversation ID

Query Parameters

ParameterTypeRequiredDefaultDescription
cursorstringNo—Cursor for pagination (message ID)
limitintegerNo50Number of messages to return (max 100)

Response 200 OK

{
  "messages": [
    {
      "id": "dm_msg_050",
      "content": "See you tomorrow!",
      "sender_id": "user_002",
      "created_at": "2025-09-12T18:00:00Z",
      "reactions": []
    },
    {
      "id": "dm_msg_049",
      "content": "Sounds good!",
      "sender_id": "user_001",
      "created_at": "2025-09-12T17:58:00Z",
      "reactions": []
    }
  ],
  "next_cursor": "dm_msg_048"
}

Send Direct Message

Section titled “Send Direct Message”
POST /v1/honeycomb/dm/{id}

Sends a message in the conversation. Also updates the conversation’s updated_at timestamp.

Path Parameters

ParameterTypeRequiredDescription
idstringYesConversation ID

Request Body

FieldTypeRequiredDescription
contentstringYesMessage content

Request Example

{
  "content": "Hey, how are you?"
}

Response 201 Created

{
  "message": {
    "id": "dm_msg_051",
    "content": "Hey, how are you?",
    "sender_id": "user_001",
    "created_at": "2025-09-12T19:30:00Z"
  }
}

React to Direct Message

Section titled “React to Direct Message”
POST /v1/honeycomb/dm/{id}/reactions

Adds or updates a reaction on a DM message. Upserts — if the user already reacted with the same emoji, the reaction is updated.

Path Parameters

ParameterTypeRequiredDescription
idstringYesConversation ID

Request Body

FieldTypeRequiredDescription
message_idstringYesTarget message ID
emojistringYesEmoji character

Request Example

{
  "message_id": "dm_msg_050",
  "emoji": "❤️"
}

Response 200 OK

{
  "reaction": {
    "message_id": "dm_msg_050",
    "user_id": "user_001",
    "emoji": "❤️"
  }
}

Calls

Section titled “Calls”

Start Call

Section titled “Start Call”
POST /v1/honeycomb/calls/start

Initiates a call to another user.

Request Body

FieldTypeRequiredDescription
target_idstringYesUser ID to call
typestringYesCall type: voice or video

Request Example

{
  "target_id": "user_002",
  "type": "video"
}

Response 200 OK

{
  "call": {
    "id": "call_001",
    "initiator_id": "user_001",
    "target_id": "user_002",
    "type": "video",
    "status": "ringing"
  }
}

Join Call

Section titled “Join Call”
POST /v1/honeycomb/calls/join

Joins a ringing call. Sets the call status to active.

Request Body

FieldTypeRequiredDescription
call_idstringYesCall ID

Request Example

{
  "call_id": "call_001"
}

Response 200 OK

{
  "call": {
    "id": "call_001",
    "initiator_id": "user_001",
    "target_id": "user_002",
    "type": "video",
    "status": "active"
  }
}

Leave Call

Section titled “Leave Call”
POST /v1/honeycomb/calls/leave

Leaves the current active call. Sets all active calls for the authenticated user to ended with an ended_at timestamp.

Request Body

No body required.

Response 200 OK

{
  "call": {
    "id": "call_001",
    "status": "ended",
    "ended_at": "2025-09-12T20:15:00Z"
  }
}

End Call

Section titled “End Call”
POST /v1/honeycomb/calls/end

Explicitly ends a specific call.

Request Body

FieldTypeRequiredDescription
call_idstringYesCall ID

Request Example

{
  "call_id": "call_001"
}

Response 200 OK

{
  "call": {
    "id": "call_001",
    "status": "ended",
    "ended_at": "2025-09-12T20:15:00Z"
  }
}

Tips

Section titled “Tips”

List Tips

Section titled “List Tips”
GET /v1/honeycomb/tips

Returns tips sent and received by the authenticated user.

Response 200 OK

{
  "sent": [
    {
      "id": "tip_001",
      "recipient_id": "user_002",
      "amount": 5.00,
      "message": "Great stream!",
      "created_at": "2025-09-10T15:00:00Z"
    }
  ],
  "received": [
    {
      "id": "tip_002",
      "sender_id": "user_003",
      "amount": 10.00,
      "message": "Thanks for the help!",
      "created_at": "2025-09-11T12:30:00Z"
    }
  ]
}

Send Tip

Section titled “Send Tip”
POST /v1/honeycomb/tips

Sends a tip to another user. Also creates a notification for the recipient.

Request Body

FieldTypeRequiredDescription
recipient_idstringYesRecipient user ID
amountnumberYesTip amount
messagestringNoOptional message with tip

Request Example

{
  "recipient_id": "user_002",
  "amount": 5.00,
  "message": "Great stream!"
}

Response 200 OK

{
  "tip": {
    "id": "tip_003",
    "sender_id": "user_001",
    "recipient_id": "user_002",
    "amount": 5.00,
    "message": "Great stream!",
    "created_at": "2025-09-12T21:00:00Z"
  }
}

Memberships

Section titled “Memberships”

Purchase Membership

Section titled “Purchase Membership”
POST /v1/honeycomb/memberships/purchase

Initiates a membership purchase and returns a Stripe checkout URL.

Request Body

FieldTypeRequiredDescription
tierstringYesMembership tier: gold ($9.99), platinum ($19.99), or other ($4.99)
success_urlstringNoRedirect URL after successful payment
cancel_urlstringNoRedirect URL if payment is cancelled

Request Example

{
  "tier": "gold",
  "success_url": "https://app.example.com/membership/success",
  "cancel_url": "https://app.example.com/membership/cancel"
}

Response 200 OK

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_abc123..."
}

Tier Pricing

TierPrice
gold$9.99/mo
platinum$19.99/mo
Other$4.99/mo

Get Membership Status

Section titled “Get Membership Status”
GET /v1/honeycomb/memberships/status

Returns the authenticated user’s current membership, or null if none exists.

Response 200 OK (active membership)

{
  "membership": {
    "id": "mem_001",
    "user_id": "user_001",
    "tier": "gold",
    "status": "active",
    "started_at": "2025-08-01T00:00:00Z",
    "expires_at": "2025-09-01T00:00:00Z"
  }
}

Response 200 OK (no membership)

{
  "membership": null
}

Badges

Section titled “Badges”

List All Badges

Section titled “List All Badges”
GET /v1/honeycomb/badges

Returns all available badges in the system.

Response 200 OK

{
  "badges": [
    {
      "id": "badge_001",
      "name": "Early Adopter",
      "description": "Joined during beta",
      "icon_url": "https://cdn.example.com/badges/early-adopter.png"
    },
    {
      "id": "badge_002",
      "name": "Top Contributor",
      "description": "Made 100+ contributions",
      "icon_url": "https://cdn.example.com/badges/top-contributor.png"
    }
  ]
}

Get User Badges

Section titled “Get User Badges”
GET /v1/honeycomb/badges/user/{id}

Returns badges earned by a specific user, including full badge details.

Path Parameters

ParameterTypeRequiredDescription
idstringYesUser ID

Response 200 OK

{
  "user_badges": [
    {
      "badge_id": "badge_001",
      "earned_at": "2025-07-01T00:00:00Z",
      "badge": {
        "id": "badge_001",
        "name": "Early Adopter",
        "description": "Joined during beta",
        "icon_url": "https://cdn.example.com/badges/early-adopter.png"
      }
    }
  ]
}

Presence

Section titled “Presence”

Update Presence

Section titled “Update Presence”
POST /v1/honeycomb/presence

Updates the authenticated user’s presence status. Upserts the record and sets last_seen to the current time.

Request Body

FieldTypeRequiredDefaultDescription
statusstringNoonlineOne of: online, away, dnd, offline

Request Example

{
  "status": "away"
}

Response 200 OK

{
  "presence": {
    "user_id": "user_001",
    "status": "away",
    "last_seen": "2025-09-12T22:00:00Z"
  }
}

Get User Presence

Section titled “Get User Presence”
GET /v1/honeycomb/presence/{userId}

Returns the presence status for a specific user. If no presence record exists, returns offline.

Path Parameters

ParameterTypeRequiredDescription
userIdstringYesUser ID

Response 200 OK (user has presence record)

{
  "user_id": "user_002",
  "status": "online",
  "last_seen": "2025-09-12T22:05:00Z"
}

Response 200 OK (no presence record)

{
  "status": "offline"
}

Typing

Section titled “Typing”

Send Typing Indicator

Section titled “Send Typing Indicator”
POST /v1/honeycomb/typing

Broadcasts a typing indicator to other users in a channel.

Request Body

FieldTypeRequiredDescription
channel_idstringYesRoom or conversation ID
is_typingbooleanYestrue when typing, false to stop

Request Example

{
  "channel_id": "room_abc123",
  "is_typing": true
}

Response 200 OK

{
  "channel_id": "room_abc123",
  "user_id": "user_001",
  "is_typing": true
}

Stickers

Section titled “Stickers”

List Sticker Packs

Section titled “List Sticker Packs”
GET /v1/honeycomb/stickers

Returns all available sticker packs with their stickers.

Response 200 OK

{
  "packs": [
    {
      "id": "pack_001",
      "name": "Fun Expressions",
      "thumbnail_url": "https://cdn.example.com/stickers/pack_001/thumb.png",
      "stickers": [
        {
          "id": "sticker_001",
          "name": "Happy",
          "image_url": "https://cdn.example.com/stickers/pack_001/happy.png"
        },
        {
          "id": "sticker_002",
          "name": "Sad",
          "image_url": "https://cdn.example.com/stickers/pack_001/sad.png"
        }
      ]
    }
  ]
}

Broadcasts

Section titled “Broadcasts”

Start Broadcast

Section titled “Start Broadcast”
POST /v1/honeycomb/broadcast/start

Starts a live broadcast for the authenticated user.

Request Body

No body required.

Response 200 OK

{
  "broadcast": {
    "id": "bc_001",
    "host_id": "user_001",
    "status": "live",
    "started_at": "2025-09-12T23:00:00Z"
  }
}

Stop Broadcast

Section titled “Stop Broadcast”
POST /v1/honeycomb/broadcast/stop

Stops all live broadcasts for the authenticated user.

Request Body

No body required.

Response 200 OK

{
  "message": "Broadcast stopped",
  "broadcast": {
    "id": "bc_001",
    "host_id": "user_001",
    "status": "ended",
    "started_at": "2025-09-12T23:00:00Z",
    "ended_at": "2025-09-12T23:45:00Z"
  }
}

Join Broadcast

Section titled “Join Broadcast”
POST /v1/honeycomb/broadcast/join

Joins a live broadcast as a viewer. Upserts the viewer record.

Request Body

FieldTypeRequiredDescription
broadcast_idstringYesBroadcast ID

Request Example

{
  "broadcast_id": "bc_001"
}

Response 200 OK

{
  "viewer": {
    "broadcast_id": "bc_001",
    "user_id": "user_002",
    "joined_at": "2025-09-12T23:05:00Z"
  }
}