> ## Documentation Index > Fetch the complete documentation index at: https://cool.computer/docs/llms.txt > Use this file to discover all available pages before exploring further. # Open the comment live channel > 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 notes 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), {"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. Notes 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. 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 notes keep arriving when the board is read every 30 seconds. ## OpenAPI ````yaml https://www.cool.computer/openapi.json get /api/computers/{id}/comments/live openapi: 3.1.0 info: title: Cool Computers API version: 1.0.0 description: >- Create and operate reachable Linux computers. Each computer keeps a stable name.cool.computer address, persistent files, and agent-ready command execution. REST requests use UTC-aligned one-minute limits: 600 requests per account identified by a recognized valid account bearer credential, a separate 600-request budget per computer-scoped credential, or 60 requests per source IP otherwise. Read-only GETs answered from API state spend a separate read budget reported as account-read or computer-read, so status polling cannot exhaust the budget that protects work and mutations. To bound authentication-provider traffic, at most 60 first-seen bearer values are checked per source IP in a minute; recognized valid credentials use their account or computer policy. Successful bearer authentication is reused for at most five seconds; transient provider failures are not cached. Revoking a credential through this API (POST /api/auth/logout or DELETE /api/api-keys/{id}) drops that reuse in every serving process, so the revoked credential is refused from the next request on; only if that announcement fails does another process keep admitting it, for at most five seconds. JSON request bodies must be sent with Content-Type: application/json; any other body answers 415 unsupported_media_type. Every error is an application/problem+json object whose type links to https://cool.computer/docs/api-reference/errors; a malformed body names the unknown field, the wrong type, or the byte where the JSON breaks. Non-exempt API responses include the structured RateLimit and RateLimit-Policy fields; request admission 429 responses use code api_request_rate_exceeded and also include Retry-After. Health, OpenAPI, webhooks, callbacks, SSE, and WebSocket endpoints are exempt from the REST request budget. Authenticated SSE connection attempts remain subject to the authentication safeguards and can receive the same typed 429 response. servers: - url: https://api.cool.computer description: Canonical API origin security: [] tags: - name: Authentication description: Obtain and manage bearer credentials. - name: Billing description: Inspect and manage the account's no-card trial or Pro plan. - name: Computers description: Create, inspect, and delete resident computers. - name: Execution description: Run commands on a computer. - name: Files description: Read and change a computer's persistent files. - name: Publishing description: >- Publish files to a computer's URL as immutable releases, with no VM. To show something, publish the files; to run something, use the computer (exec, terminal, services), which gets Linux on first use. - name: Services description: >- Manage processes and select the HTTP port exposed at a computer's stable address. - name: Email description: Read and send mail through a computer's inbox. - name: Comments description: >- Notes people leave on a computer's page, when its owner switched comments on: the owner, the people it is shared with and, when the computer is public, any signed-in person. The owner's agent reads every open note and resolves it. - name: Network description: Control a computer's public visibility and outbound network policy. - name: Sharing description: Invite people to use a computer without granting owner controls. - name: Public description: Unauthenticated discovery endpoints. - name: Secrets description: Inspect secret sets and their audit history; values are never returned. - name: Providers description: Inspect connected coding-agent provider credentials. - name: GitHub description: Inspect the GitHub App installations connected to the account. - name: Terminals description: Inspect a computer's terminal sessions. - name: Operator description: Read the operator agent's conversations, turns, and events. - name: Feedback description: >- Tell the Cool Computers team what works and what does not, with or without an account. externalDocs: description: Cool Computers agent registration guide url: https://www.cool.computer/auth.md paths: /api/computers/{id}/comments/live: get: tags: - Comments summary: Open the comment live channel description: >- 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 notes 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), {"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. Notes 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. 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 notes keep arriving when the board is read every 30 seconds. operationId: openComputerCommentLive parameters: - $ref: '#/components/parameters/ComputerID' responses: '101': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- Switching Protocols. The WebSocket is open; the first frame is a board ping. '400': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- Bad Request. `comment_live_upgrade_required`: this is not a same-origin WebSocket handshake; read the notes with GET /api/computers/{id}/comments/all instead. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': $ref: '#/components/responses/Unauthorized' '404': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' description: >- 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 for a session cookie or 600 a minute per account for a bearer; wait for Retry-After seconds. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/Problem' security: - bearerAuth: [] components: parameters: ComputerID: name: id in: path required: true description: Stable public computer identifier. schema: type: string minLength: 1 example: cmp_123 headers: RateLimit: description: >- The applied policy name, requests remaining after this request, and whole seconds until the current UTC-aligned window resets. schema: type: string pattern: >- ^"(account|account-read|computer|computer-read|source|comment-board|comment-live)";r=[0-9]+;t=([1-9]|[1-5][0-9]|60)$ examples: - '"account";r=599;t=42' - '"computer-read";r=598;t=42' RateLimit-Policy: description: >- The selected policy name, quota, and window in seconds. Valid account credentials use account or account-read with q=600, computer credentials use computer or computer-read with q=600, unauthenticated or unrecognized requests use source with q=60 for their source IP, a browser session's read of a comment board uses comment-board with q=300 for its source IP, and its handshake of a comment live channel uses comment-live with q=60 for its source IP. schema: type: string pattern: >- ^("(account|account-read|computer|computer-read)";q=600|"source";q=60|"comment-board";q=300|"comment-live";q=60);w=60$ examples: - '"account";q=600;w=60' - '"computer-read";q=600;w=60' Retry-After: description: >- Whole seconds to wait after an api_request_rate_exceeded, comment_rate_exceeded, comment_site_rate_exceeded, comment_live_full or computer_starting response before retrying (up to 3600 for comment_site_rate_exceeded, whose window is an hour). Other 429 problem codes describe separate resource or provider limits and do not inherit this retry value. schema: type: integer minimum: 1 maximum: 3600 examples: - 42 schemas: Problem: type: object additionalProperties: false required: - type - title - status - code - detail properties: type: type: string format: uri description: >- https://cool.computer/docs/api-reference/errors, the page that explains every code. title: type: string status: type: integer minimum: 400 maximum: 599 code: type: string pattern: ^[a-z0-9_]+$ detail: type: string resolution: type: string context: type: object additionalProperties: true responses: Unauthorized: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Unauthorized. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' InternalServerError: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Internal Server Error. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Problem: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- A machine-readable API error with a stable code and recovery instruction. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: WorkOS user or agent access token, or Cool Computers API key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.