---
title: "Open the comment live channel"
description: "The comment layer's live channel: a WebSocket, not an HTTP read."
canonical: "https://www.cool.computer/docs/api-reference/comments/open-the-comment-live-channel"
---
# Open the comment live channel

> The comment layer's live channel: a WebSocket, not an HTTP read.

```http
GET https://api.cool.computer/api/computers/{id}/comments/live
```

The comment layer's live channel: a WebSocket, not an HTTP read. Send a WebSocket handshake (Upgrade: websocket) from the site's own origin (or with no Origin header) with the browser session cookie, which is what the comment layer does, or with an account bearer in Authorization, which is for tools. Allowed: the owner, anyone the computer is shared with and, when the computer is public, any signed-in person (a person's own sign-in, not an organization API key or the computer's runtime token), while comments are on for the computer. Every message is a text JSON object with a t field. The client's messages are at most 1 KiB each (a larger one closes the socket with 1009); the server's are bounded by their content instead, not by 1 KiB: a here message names at most 8 people with names of at most 40 characters, a cur message has at most 8 entries, and board and pong carry nothing, so read them without a 1 KiB limit. The server sends {"t":"board"} (the comments changed, or you just joined: read the board with ?since=, at most one ping a second), {"t":"here","people":[{"id":3,"name":"Dana","owner":false}],"more":0} (the others on your page, the 8 most recently active, names only and never emails; id is a number that is only meaningful in this room), {"t":"cur","c":[[3,4210,1830],[5]]} (pointer moves of listed people, [id] alone means hidden) and {"t":"pong"}. The client sends {"t":"page","page":"/pricing"} (the page path, within 10 seconds of opening), {"t":"cur","x":4210,"y":1830} (x in basis points of the page width 0 to 10000, y in CSS pixels from the top 0 to 1000000; a frame out of range closes the channel), {"t":"cur"} (hide my pointer) and {"t":"ping"} (every 25 seconds). A frame the server refuses, a binary frame or a flood closes the socket with 1008, an oversized one with 1009; do not reconnect for 60 seconds. 1012 (restart or the 10 minute lifetime) and 1013 (too slow) mean reconnect. 4001 means comments were switched off, the computer is gone or private, or access was revoked: read the board, which decides. Presence and pointers live in memory of one server process and are never stored. Comments are never sent on the socket; there is no history to resume from, so after any reconnect read the board with since. A request that is not a same-origin WebSocket handshake is answered 400 without spending any allowance. Admission has two paths with separate budgets. With no Authorization header (a browser session), a request with no session cookie is answered 401 at once and the rest spend the comment-live allowance of 60 handshakes a minute per source IP (IPv6 /64). With an Authorization header, a valid account bearer without any cookie opens the socket and spends the account-read budget of 600 requests a minute shared with the account's other reads, not the per-IP one; an invalid bearer, or a computer's runtime token, is 401. At most 40 sockets per computer (4 more only for its owner), 6 per person and 1500 per process: beyond that 429 comment_live_full, and comments keep arriving when the board is read every 30 seconds.

## Authorization

- A Cool Computers API key, user access token, or claimed agent access token in the Authorization header. Follow https://www.cool.computer/auth.md for agent registration and https://www.cool.computer/authentication.md for direct user credentials.

## Parameters

- `id` (path, string, at least 1 characters, required): The computer's name, such as agent-atlas, or its id (cmp_…). Every caller may use either, the computer's own runtime token included.

## Responses

- `101`: Switching Protocols. The WebSocket is open; the first frame is a board ping.
- `400`: Bad Request. `comment_live_upgrade_required`: this is not a same-origin WebSocket handshake; read the comments with GET /api/computers/{id}/comments/all instead.
- `401`: Unauthorized.
- `404`: Not Found. `comments_off`: comments are off for the computer, so there is no live channel; the board says so. The computer itself is also 404 for anyone it is not shared with when it is private.
- `429`: Too Many Requests. `comment_live_full`: a socket cap is reached; keep reading the board every 30 seconds and open the socket again after Retry-After. `api_request_rate_exceeded`: a handshake budget is spent, 60 a minute per source IP (IPv6 /64) for a session cookie or 600 a minute per account for a bearer; wait for Retry-After seconds.
- `500`: Internal Server Error.
- `default`: A machine-readable API error with a stable code and recovery instruction.

An error is an `application/problem+json` document with a stable `code`; [API errors](/docs/api-reference/errors) says how to handle one.

## Example

```sh
curl "https://api.cool.computer/api/computers/$PARAM_ID/comments/live" \
  -H "authorization: Bearer $TOKEN"
```
