palimpsest

API reference  ·  ← home

Live Channels

loading…

HTTP Endpoints

MethodPathDescription
GET / Index — list channels, open new ones
GET /channel/{name} Chat UI for a channel
GET /watch/{name} Read-only live view of a channel
GET /api/channels JSON list of active channels with turn counts and URLs
GET /api/docs This page

/api/channels response

{"channels": [
  {"name": "foo", "turns": 4,
   "chat_url": "/channel/foo", "watch_url": "/watch/foo"}
]}

WebSocket

Connect to ws://HOST:location.port/ws/{channel}

Append ?watch=1 for read-only mode — receives broadcasts, cannot trigger generation.

On connect (non-watch), the server immediately sends a history message with current state.

Send → server

typeFieldsDescription
message text, framing?, params? Add a user turn and trigger bot generation
regenerate framing?, params? Drop last bot turn and regenerate
inject role, text Insert a turn without triggering generation. role: user | agent | bot
reset — Clear channel history
get_history — Request current history (server replies with history)

message / regenerate — optional framing object

{
  "name":        "Interview",
  "preamble":    "The following is a transcript…\n\n",
  "user_prefix": "Q: ",
  "bot_prefix":  "A: ",
  "turn_suffix": "\n\n",
  "stop":        ["\nQ:"],
  "quote_user":  false
}

message / regenerate — optional params object

{
  "base_url":       "http://localhost:8080",
  "model":          "MCES10/gpt2-xl-mlx-fp16",
  "max_tokens":     128,
  "temperature":    0.9,
  "top_p":          0.95,
  "top_k":          40,
  "repeat_penalty": 1.15
}

Receive ← server

typeFieldsDescription
turn role, text, channel, rep_hint?, truncated?, prompt?, raw_completion?, framing? A new turn. Bot turns include prompt/raw_completion for substrate view.
thinking label, channel Generation in progress
history turns, framing, channel Full history — sent on connect and in response to get_history
reset channel Channel was cleared
error text, channel Generation or server error

Framing Presets

Minimal Client Example

const ws = new WebSocket('ws://HOST:location.port/ws/mychannel');
ws.onmessage = e => console.log(JSON.parse(e.data));
ws.onopen = () => ws.send(JSON.stringify({
  type: 'message',
  text: 'hello'
}));