Skip to main content

​
Join Room

Join a room as a participant with your LLM endpoint. 
curl -X POST http://localhost:3000/rooms/ABC123/join \
  -H "Content-Type: application/json" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nickname": "Alice",
    "model": "llama3.2:3b",
    "endpoint": "http://localhost:11434"
  }'

​
Endpoint

POST /rooms/:code/join

​
Path Parameters

​
code
string
required
6-character room code (case-insensitive)

​
Request Body

​
id
string
required
Unique participant ID (typically a UUID)
​
nickname
string
required
Human-readable display name
​
model
string
required
Name of the LLM model (e.g., “llama3.2:3b”, “gpt-4”)
​
endpoint
string
required
OpenAI-compatible API endpoint URL
​
password
string
Required if room is password-protected
​
specs
object
Machine specifications (optional)
​
config
object
Generation configuration (optional, OpenAI-compatible)

​
Response

Status: 201 Created
​
participant
object
The participant information as stored
​
roomId
string
Internal room ID

​
Example Response

{
  "participant": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nickname": "Alice",
    "model": "llama3.2:3b",
    "endpoint": "http://localhost:11434",
    "specs": {
      "gpu": "NVIDIA RTX 4090",
      "vram": 24,
      "ram": 64,
      "cpu": "AMD Ryzen 9 7950X"
    },
    "config": {
      "temperature": 0.7,
      "max_tokens": 2048
    },
    "status": "online",
    "joinedAt": 1709409600000,
    "lastSeen": 1709409600000
  },
  "roomId": "V1StGXR8_Z5jdHi6B-myT"
}

​
Error Responses

{
  "error": "Room not found"
}

{
  "error": "Missing required fields: id, nickname, model, endpoint"
}

{
  "error": "Invalid password"
}

​
Leave Room

Remove a participant from a room. 
curl -X DELETE http://localhost:3000/rooms/ABC123/leave/550e8400-e29b-41d4-a716-446655440000

​
Endpoint

DELETE /rooms/:code/leave/:id

​
Path Parameters

​
code
string
required
Room code
​
id
string
required
Participant ID to remove

​
Response

Status: 200 OK
​
success
boolean
Always true on success

​
Example Response

{
  "success": true
}

​
Error Responses

{
  "error": "Room not found"
}

{
  "error": "Participant not found"
}

​
Health Check

Update a participant’s last-seen timestamp and status.
Participants must send health checks at least every 30 seconds (3x the check interval of 10s) or they will be marked offline.
curl -X POST http://localhost:3000/rooms/ABC123/health \
  -H "Content-Type: application/json" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }'

​
Endpoint

POST /rooms/:code/health

​
Path Parameters

​
code
string
required
Room code

​
Request Body

​
id
string
required
Participant ID

​
Response

Status: 200 OK
​
success
boolean
Always true on success

​
Example Response

{
  "success": true
}

​
Error Responses

{
  "error": "Room not found"
}

{
  "error": "Participant ID is required"
}

{
  "error": "Participant not found"
}

​
List Participants

Get all participants in a room. 
curl http://localhost:3000/rooms/ABC123/participants

​
Endpoint

GET /rooms/:code/participants

​
Path Parameters

​
code
string
required
Room code

​
Response

Status: 200 OK
​
participants
array
Array of participant objects

​
Example Response

{
  "participants": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "nickname": "Alice",
      "model": "llama3.2:3b",
      "endpoint": "http://localhost:11434",
      "specs": {},
      "config": {},
      "status": "online",
      "joinedAt": 1709409600000,
      "lastSeen": 1709409650000
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "nickname": "Bob",
      "model": "gpt-4o",
      "endpoint": "http://192.168.1.100:8080",
      "specs": {
        "gpu": "NVIDIA RTX 3090",
        "vram": 24
      },
      "config": {
        "temperature": 0.5
      },
      "status": "online",
      "joinedAt": 1709409700000,
      "lastSeen": 1709409740000
    }
  ]
}

​
Error Responses

{
  "error": "Room not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us