Rooms API

Endpoints for creating, listing, and managing chat rooms.

Overview

Chat rooms are either public (visible to all users) or private (visible only to members). Users can create, join, leave, and delete rooms.

Endpoint Summary

Endpoints

List Rooms

Get all public rooms and private rooms visible to the authenticated user (if provided).

GET /api/rooms?username=alice

{
  "rooms": [
    {
      "id": "general",
      "name": "General Chat",
      "type": "public",
      "createdAt": 1704067200000,
      "userCount": 15
    },
    {
      "id": "abc123",
      "name": "Private Room",
      "type": "private",
      "members": ["alice", "bob"],
      "createdAt": 1704153600000,
      "userCount": 2
    }
  ]
}

Create Room

Create a new chat room. Requires authentication.

Notes:

• Public room creation is admin-only (ryo).
• Private room creation requires at least one member; creator is auto-included.

POST /api/rooms
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "type": "private",
  "members": ["alice", "bob"],
  "name": "Project Discussion"  // optional
}

{
  "room": {
    "id": "abc123def456",
    "name": "@alice, @bob",
    "type": "private",
    "members": ["alice", "bob"],
    "createdAt": 1704067200000,
    "userCount": 2
  }
}

Get Room

Get details for a specific room.

GET /api/rooms/{id}

{
  "room": {
    "id": "general",
    "name": "General Chat",
    "type": "public",
    "createdAt": 1704067200000,
    "userCount": 15
  }
}

Delete Room

Delete a room.

• Public rooms: admin-only (ryo).

• Private rooms: members can "delete" by leaving; room is removed automatically when <= 1 members remain.

DELETE /api/rooms/{id}
Authorization: Bearer {token}
X-Username: alice

{
  "success": true
}

Join Room

Join a room to participate in chat.

POST /api/rooms/{id}/join
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "username": "alice"
}

{
  "success": true
}

Leave Room

Leave a room.

POST /api/rooms/{id}/leave
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "username": "alice"
}

{
  "success": true
}

List Active Users

Get list of users currently active in a room.

GET /api/rooms/{id}/users

{
  "users": [
    {
      "username": "alice",
      "joinedAt": 1704067200000
    },
    {
      "username": "bob",
      "joinedAt": 1704153600000
    }
  ]
}

Room Types

Public Rooms

• Visible to all users in room listings

• Anyone can join without invitation
• Default room type for general discussions

Private Rooms

• Only visible to members

• Created with a specific member list
• Ideal for direct messages or group chats

Error Responses

Related

• Auth API - Authentication endpoints

• Messages API - Message endpoints
• Presence API - Presence tracking