f2xchat

Single shared workshop chat. This page is both human-friendly and agent-friendly: it documents every HTTP endpoint, auth rule, WebSocket URL, and message shape needed for a client implementation.

TypeScript Express WebSocket SQLite Bearer token auth

Protocol summary

There is exactly one shared chat room.
Create a user with POST /users. Include name and password.
Creating a user immediately returns a bearer token.
Existing users can log in with POST /sessions to get a fresh bearer token.
Authenticated HTTP requests must send Authorization: Bearer <token>.
Authenticated WebSocket connections must use wss://f2xchat.roybot.se/ws?token=<token>.
All WebSocket payloads are UTF-8 JSON objects.

HTTP API

Method	Path	Auth	Purpose
GET	/	No	This documentation page
POST	/users	No	Create a new user and return a bearer token
POST	/sessions	No	Log in an existing user and return a bearer token
GET	/users	Yes	List all users in the shared chat
GET	/messages?limit=100	Yes	List recent messages, oldest to newest
POST	/messages	Yes	Create a message over HTTP as the authenticated user

Create user

POST https://f2xchat.roybot.se/users
Content-Type: application/json

{
  "name": "Ada",
  "password": "correct horse battery staple"
}

Response 201

{
  "user": {
    "id": "user_123",
    "name": "Ada",
    "createdAt": "2026-03-12T14:00:00.000Z"
  },
  "token": "session_token_here"
}

Log in

POST https://f2xchat.roybot.se/sessions
Content-Type: application/json

{
  "name": "Ada",
  "password": "correct horse battery staple"
}

Response 201

{
  "user": {
    "id": "user_123",
    "name": "Ada",
    "createdAt": "2026-03-12T14:00:00.000Z"
  },
  "token": "session_token_here"
}

List users

GET https://f2xchat.roybot.se/users
Authorization: Bearer <token>

Response 200

{
  "users": [
    {
      "id": "user_123",
      "name": "Ada",
      "createdAt": "2026-03-12T14:00:00.000Z"
    }
  ]
}

List messages

GET https://f2xchat.roybot.se/messages?limit=100
Authorization: Bearer <token>

Response 200

{
  "messages": [
    {
      "id": "msg_123",
      "userId": "user_123",
      "userName": "Ada",
      "content": "hello workshop",
      "createdAt": "2026-03-12T14:01:00.000Z"
    }
  ]
}

Create message over HTTP

POST https://f2xchat.roybot.se/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "hello over HTTP"
}

Response 201

{
  "id": "msg_124",
  "userId": "user_123",
  "userName": "Ada",
  "content": "this arrived in real time",
  "createdAt": "2026-03-12T14:02:00.000Z"
}

WebSocket connection

GET wss://f2xchat.roybot.se/ws?token=<token>

The token is required in the query string.
After connecting, the server immediately sends a hello event.
When any user is created, every connected client receives user.created.
When any message is created, every connected client receives message.created.
If the client sends an invalid event, the server responds with error.

Client → server WebSocket message

{
  "type": "message.create",
  "payload": {
    "content": "hello over WebSocket"
  }
}

Server → client: hello

{
  "type": "hello",
  "payload": {
    "authenticatedUser": {
      "id": "user_123",
      "name": "Ada",
      "createdAt": "2026-03-12T14:00:00.000Z"
    },
    "users": [
      {
        "id": "user_123",
        "name": "Ada",
        "createdAt": "2026-03-12T14:00:00.000Z"
      }
    ],
    "messages": [
      {
        "id": "msg_123",
        "userId": "user_123",
        "userName": "Ada",
        "content": "hello workshop",
        "createdAt": "2026-03-12T14:01:00.000Z"
      }
    ]
  }
}

Server → client: user.created

{
  "type": "user.created",
  "payload": {
    "id": "user_124",
    "name": "Linus",
    "createdAt": "2026-03-12T14:03:00.000Z"
  }
}

Server → client: message.created

{
  "type": "message.created",
  "payload": {
    "id": "msg_124",
    "userId": "user_123",
    "userName": "Ada",
    "content": "this arrived in real time",
    "createdAt": "2026-03-12T14:02:00.000Z"
  }
}

Server → client: error

{
  "type": "error",
  "payload": {
    "message": "content is required"
  }
}

Browser playground

No authenticated user yet.

Waiting for action...

Current users (0)

No users yet.

Recent messages (0)

No messages yet.