API Reference#

ChatAPI provides REST and WebSocket APIs for messaging and bots. All endpoints (except /health and /metrics) require a JWT Bearer token.

Authentication#

Authorization: Bearer <jwt>

Your backend signs JWTs with JWT_SECRET. The sub claim is the user ID for the request. There are no API keys, no master keys, and no session tokens.

WebSocket connections accept:

  • ?token=<jwt> query parameter — for browser clients
  • Authorization: Bearer <jwt> header — for server-side clients

REST API#

MethodEndpointDescription
GET/roomsList rooms the user belongs to
POST/roomsCreate a room (DM or group)
GET/rooms/{room_id}Get room details
PATCH/rooms/{room_id}Update room name or metadata
GET/rooms/{room_id}/membersList room members
POST/rooms/{room_id}/membersAdd a member (or bot) to a room
POST/rooms/{room_id}/messagesSend a message
GET/rooms/{room_id}/messagesGet messages (paginated)
PUT/rooms/{room_id}/messages/{message_id}Edit a message
DELETE/rooms/{room_id}/messages/{message_id}Delete a message
POST/acksAcknowledge message delivery
POST/botsRegister a bot
GET/botsList bots
GET/bots/{bot_id}Get a bot
DELETE/bots/{bot_id}Delete a bot
GET/admin/dead-lettersFailed message deliveries
GET/healthService health check (no auth)
GET/metricsLive server counters (no auth)

WebSocket API#

Connect to /ws with a JWT:

ws://localhost:8080/ws?token=<jwt>        # browser
ws://localhost:8080/ws                    # server (Authorization header)

Client → Server events#

typeDescription
send_messageSend a message to a room
ackAcknowledge messages up to a sequence number
typing.startBroadcast typing started
typing.stopBroadcast typing stopped
pingKeep-alive (no response)

Server → Client events#

typeDescription
messageNew message in a room
message.stream.startLLM bot response starting
message.stream.deltaToken chunk from LLM stream
message.stream.endStream complete, message persisted
message.stream.errorLLM call failed — discard partial content
errorRequest rejected (e.g. rate limited)
ack.receivedAnother user acknowledged messages
typingAnother user’s typing status
presence.updateUser came online or went offline
server.shutdownServer is restarting

Reference#