POST /api/auth/token
Content-Type: application/json

{
  "password": "optional-password"
}

{
  "token": "jwt-token-string",
  "expiresIn": 86400
}

POST /api/sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "command": "zsh",
  "args": [],
  "cwd": "/Users/username",
  "env": {},
  "name": "Session Name",
  "cols": 80,
  "rows": 24
}

{
  "id": "session-uuid",
  "name": "Session Name",
  "created": "2024-01-01T00:00:00Z",
  "status": "running",
  "pid": 12345
}

GET /api/sessions
Authorization: Bearer <token>

[
  {
    "id": "session-uuid",
    "name": "Session 1",
    "created": "2024-01-01T00:00:00Z",
    "status": "running",
    "pid": 12345
  }
]

GET /api/sessions/:id
Authorization: Bearer <token>

DELETE /api/sessions/:id
Authorization: Bearer <token>

POST /api/sessions/:id/resize
Authorization: Bearer <token>
Content-Type: application/json

{
  "cols": 120,
  "rows": 40
}

const ws = new WebSocket('ws://localhost:4020/api/sessions/:id/ws');
ws.binaryType = 'arraybuffer';

[0xBF][4-byte length][UTF-8 data]

{
  "type": "input",
  "data": "ls -la\n"
}

{
  "type": "resize",
  "cols": 120,
  "rows": 40
}

{
  "type": "ping"
}

GET /api/health

{
  "status": "healthy",
  "uptime": 3600,
  "version": "1.0.0",
  "sessions": 5
}

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

┌──────────┬──────────────┬──────────────┐
│ Magic    │ Length       │ Data         │
│ (1 byte) │ (4 bytes)    │ (n bytes)    │
│ 0xBF     │ Big-endian   │ UTF-8        │
└──────────┴──────────────┴──────────────┘

// Encoding
function encodeBuffer(data: string): ArrayBuffer {
  const encoded = new TextEncoder().encode(data);
  const buffer = new ArrayBuffer(5 + encoded.length);
  const view = new DataView(buffer);
  view.setUint8(0, 0xBF);
  view.setUint32(1, encoded.length, false);
  new Uint8Array(buffer, 5).set(encoded);
  return buffer;
}

// Decoding
function decodeBuffer(buffer: ArrayBuffer): string {
  const view = new DataView(buffer);
  if (view.getUint8(0) !== 0xBF) throw new Error('Invalid magic byte');
  const length = view.getUint32(1, false);
  return new TextDecoder().decode(new Uint8Array(buffer, 5, length));
}

{
  "version": 2,
  "width": 80,
  "height": 24,
  "timestamp": 1234567890,
  "env": {
    "SHELL": "/bin/zsh",
    "TERM": "xterm-256color"
  }
}

[timestamp, "o", "output data"]