4. Public API

Public API

ChatCLI exposes two server processes:

Process	Default address	Protocol
HTTP API	https://chat.puam.be:5123	HTTP/HTTPS
WebSocket server	wss://ws.chat.puam.be/ws	WebSocket (WSS)

All HTTP endpoints that require authentication expect a valid session token in the request body.

---

HTTP API

Base routes

Method	Path	Description
GET	/	Renders the welcome page
GET, POST	/verify-connection	Checks server connectivity; returns a status confirmation
GET, POST	/subscribe	Subscribe an email address to notifications

---

User routes — /user/...

Method	Path	Description
POST	/user/register	Create a new account; sends an email verification code
POST	/user/verify-email	Confirm an email address using the verification code
POST	/user/resend-verification	Re-send the verification email
POST	/user/login	Authenticate; returns access and refresh tokens
GET, POST	/user/reset-password	Complete a password reset (also renders the reset form)
POST	/user/reset-password-request	Initiate a password reset — sends a reset link by email
POST	/user/refresh-token	Rotate a valid refresh token and issue new tokens
POST	/user/profile	Fetch the authenticated user's profile data
POST	/user/submit-profile	Update username or email
POST	/user/change-password	Change password while logged in
POST	/user/logout	Invalidate the current session token
POST	/user/logout-all	Invalidate all active sessions for the account

---

Chat routes — /chat/...

Method	Path	Description
POST	/chat/fetch-chats	Retrieve the authenticated user's active chats
POST	/chat/create-chat	Create a new 1:1 chat between two users
POST	/chat/create-group	Create a new group chat
POST	/chat/add-members	Add one or more users to a group chat
POST	/chat/remove-members	Remove one or more users from a group chat
POST	/chat/get-members	List the members of a chat
POST	/chat/messages	Fetch messages from a specific chat
POST	/chat/archive-chat	Archive a chat
POST	/chat/fetch-archived	Retrieve the user's archived chats
POST	/chat/unarchive-chat	Unarchive a previously archived chat

---

WebSocket API

Endpoint: wss://ws.chat.puam.be/ws

VoIP call endpoint: wss://ws.chat.puam.be/ws/call/{call_id}

Connection flow

1. Open a WebSocket connection to the endpoint above.
2. Send an authentication message containing a valid session token.
3. Once authenticated, the server associates your connection with your user account.

Events (outgoing — client → server)

Event	Description
Authenticate	Send session token to identify the connection
Join chat	Subscribe to messages for a specific chat
Send message	Broadcast a new message to a chat
Typing	Notify other participants that you are composing

Events (incoming — server → client)

Event	Description
New message	A new message was posted in a chat you are in
Typing indicator	Another user in a chat started or stopped typing
Presence update	A user's online / offline status changed
Chat list update	You were added to a new chat

VoIP (LiveKit)

Voice calls are handled by a dedicated WebSocket endpoint (/ws/call/{call_id}) that proxies signalling through a LiveKit server. The client receives a LiveKit token from the HTTP API before joining the call WebSocket.