API Documentation

How to interact with the Vybez API and real-time services.

RESTful API (HTTP)

These are the standard HTTP endpoints for user management, rooms, and profiles.

POST /signup

Creates a new user account.

Request Body: 
{
    "username": "new_user",
    "password": "a_password",
    "chat_color": "#ff00ff"
}
Responses:
  • 201 Created - User created successfully.
  • 409 Conflict - Username already exists.
POST /login

Authenticates a user and starts a session.

Request Body: 
{
    "username": "existing_user",
    "password": "their_password",
    "client": "web"  // Optional: "web", "desktop", "api", "discord"
}

🔍 Client Detection: The optional client field identifies the login source. Valid values: web (website), desktop (desktop app), api (external API), discord (Discord bot). Defaults to web if not specified. This appears in server logs and Discord webhook notifications with emojis (🌐 Web, 💻 Desktop, 🤖 API/Discord).

Responses:
  • 200 OK - Login successful.
  • 401 Unauthorized - Invalid credentials.
POST /logout

Destroys the current user session.

Request Body: None
GET /check-session

Checks if the current browser has a valid session.

Response Body (Logged In): 
{
    "loggedIn": true,
    "user": { "username": "test", "color": "#ff0000", ... }
}
Response Body (Logged Out): 
{ "loggedIn": false }

Health & Monitoring

GET /health

Server health check endpoint for monitoring and uptime verification.

Response Body (Healthy): 
{
    "status": "OK",
    "uptime": 14.977,
    "timestamp": "2025-10-13T23:19:05.476Z",
    "database": "connected"
}
Response Body (Database Error): 
{
    "status": "ERROR",
    "uptime": 245.621,
    "timestamp": "2025-10-13T23:25:30.123Z",
    "database": "disconnected"
}
Responses:
  • 200 OK - Server and database are healthy.
  • 503 Service Unavailable - Database connection error.

💡 Use Case: Configure monitoring services (UptimeRobot, Google Cloud Monitoring, etc.) to ping this endpoint every 5-10 minutes to verify server availability.

Room Management

GET /rooms

Retrieves all available chat rooms (default and custom).

Authorization: Requires active session 
{
    "rooms": [
        {
            "id": 1,
            "name": "#general",
            "created_by": "system",
            "created_at": "2025-10-06T...",
            "is_default": true
        },
        {
            "id": 4,
            "name": "#gaming",
            "created_by": "john_doe",
            "created_at": "2025-10-06T...",
            "is_default": false
        }
    ]
}
POST /rooms

Creates a new custom chat room.

Authorization: Requires active session Request Body: 
{
    "name": "gaming"
}

Note: The # symbol is added automatically if not provided.

Responses:
  • 201 Created - Room created successfully. Broadcasts roomCreated event to all clients.
  • 409 Conflict - Room already exists.
  • 400 Bad Request - Room name is required.
DELETE /rooms/:name

Deletes a custom chat room. Default rooms (#general, #tech, #random) cannot be deleted.

Authorization: Requires active session Example: 
DELETE /rooms/%23gaming
Responses:
  • 200 OK - Room deleted successfully. Broadcasts roomDeleted event to all clients.
  • 403 Forbidden - Cannot delete default room.

User Management & Settings

GET /settings

Discord-style settings page with categorized navigation (Appearance, Profile, My Account, Privacy & Safety, Advanced).

Authorization: Requires active session

⚙️ Features: Light/dark theme toggle, profile customization (avatar, bio, status, chat color), account management (username, email), and account deletion.

POST /upload-avatar

Uploads a user profile avatar image (max 10MB).

Authorization: Requires active session Content-Type: multipart/form-data Form Fields:
  • avatar - Image file (JPG, PNG, GIF)
Response: 
{
    "avatarUrl": "/uploads/avatar-abc123.jpg"
}
POST /update-profile

Updates user profile information (bio, status, chat color, email).

Authorization: Requires active session Request Body (partial updates allowed): 
{
    "bio": "Coffee enthusiast and coder",
    "status": "Online",
    "chat_color": "#3b82f6",
    "email": "user@example.com"  // Optional, nullable
}

🔐 Privacy: Email addresses are optional and only visible to the account owner and admins. Set to null to remove email.

POST /change-username

Changes the user's username with password confirmation.

Authorization: Requires active session Request Body: 
{
    "newUsername": "new_username",
    "password": "current_password"
}
Responses:
  • 200 OK - Username changed successfully. User must re-login.
  • 400 Bad Request - Invalid input or username requirements not met.
  • 401 Unauthorized - Incorrect password.
  • 409 Conflict - Username already taken.
POST /delete-account

Permanently deletes the user's account and all associated data.

Authorization: Requires active session Request Body: 
{
    "password": "current_password"
}

⚠️ Warning: This action is permanent and cannot be undone. Deletes user profile, all messages, private messages, rooms created, and reactions.

Responses:
  • 200 OK - Account deleted successfully.
  • 401 Unauthorized - Incorrect password.

File Upload & Messaging

POST /upload-file

Uploads a file for sharing in chat (max 10MB).

Authorization: Requires active session Content-Type: multipart/form-data

Supported types: images, PDFs, documents, videos

GET /private-messages/:username

Retrieves private message history with a specific user.

Authorization: Requires active session

Real-Time API (Socket.IO)

These are the events used for real-time communication after a user is authenticated on the /chat page.

Events Emitted by the Client

switchRoom

Tells the server to move the user to a different chat room.

Payload: "roomName" (string), e.g., "#tech"
chatMessage

Sends a new public message to the current room.

Payload: 
{ 
    "text": "Hello everyone!",
    "fileUrl": "/uploads/...",  // optional
    "fileType": "image/jpeg"    // optional
}
typing

Indicates user is typing or stopped typing.

Payload: true (typing) or false (stopped)
privateMessage

Sends a private message to another user.

Payload: 
{ 
    "to": "recipient_username",
    "text": "Hey there!"
}
addReaction

Adds an emoji reaction to a message.

Payload: 
{ 
    "messageId": 123,
    "emoji": "👍"
}

Events Emitted by the Server

roomList

Sent to a client when they connect, containing all available rooms.

Payload: 
["#general", "#tech", "#random", "#gaming"]
loadHistory

Sent to a client when they join a room, containing recent messages.

Payload: 
{
    "room": "#general",
    "messages": [
        { 
            "id": 12345,
            "user": "admin_user",
            "display_name": "Admin User",
            "text": "Welcome to the room!",
            "color": "#ff0000",
            "timestamp": "2025-10-06T...",
            "avatar": "/uploads/...",
            "role": "admin",  // "admin" or "user"
            "fileUrl": "/uploads/...",  // optional
            "fileType": "image/jpeg"    // optional
        }
    ]
}

🛡️ Admin Indicator: Historical messages from users with role: "admin" display with an Electric Magenta shield icon next to their username in the chat UI.

chatMessage

Broadcasts a new public message to all clients in a room.

Payload: 
{
    "id": 12345,
    "user": "test_user",
    "display_name": "Test User",
    "text": "Hello everyone!",
    "color": "#ff0000",
    "timestamp": "2025-10-06T...",
    "avatar": "/uploads/...",
    "role": "admin",  // "admin" or "user"
    "mentions": ["user1", "user2"],
    "fileUrl": "/uploads/...",  // optional
    "fileType": "image/jpeg"    // optional
}

🛡️ Admin Indicator: Messages from users with role: "admin" display with an Electric Magenta shield icon next to their username in the chat UI for easy role identification.

updateUserList

Broadcasts the updated list of all online users.

Payload: 
[
    { 
        "username": "admin_user",
        "color": "#ff0000",
        "avatar": "/uploads/...",
        "bio": "Server administrator",
        "status": "online",
        "role": "admin",    // "admin" or "user"
        "isOnline": true
    },
    ...
]

🛡️ Admin Indicator: Users with role: "admin" display with an Electric Magenta shield icon next to their username in the members list UI.

typingUsers

Broadcasts which users are currently typing in the current room.

Payload: 
["user1", "user2"]
roomCreated

Broadcasted when a new custom room is created.

Payload: 
{
    "id": 5,
    "name": "#gaming",
    "created_by": "john_doe",
    "created_at": "2025-10-06T...",
    "is_default": false
}
roomDeleted

Broadcasted when a custom room is deleted.

Payload: 
{ "name": "#gaming" }
reactionsUpdate

Sent when reactions are updated for a message.

Payload: 
{
    "messageId": 123,
    "reactions": [
        { "emoji": "👍", "username": "alice" },
        { "emoji": "❤️", "username": "bob" }
    ]
}