---
title: "Get the comment board"
description: "On a site published without an account, until it is claimed, also accepts its claim key (claimKeyAuth) as its publisher's agent, with owner rights and runtime-token answers on that site alone."
canonical: "https://www.cool.computer/docs/api-reference/comments/get-the-comment-board"
---
# Get the comment board

> On a site published without an account, until it is claimed, also accepts its claim key (claimKeyAuth) as its publisher's agent, with owner rights and runtime-token answers on that site alone.

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

On a site published without an account, until it is claimed, also accepts its claim key (claimKeyAuth) as its publisher's agent, with owner rights and runtime-token answers on that site alone. Also accepts this computer's own runtime token, with the computer named by its name or id; a different computer returns 404. Sharing is checked per request using the integration-withholding definition (active shares and pending shares still valid or being accepted). Unshared: owner comment rights. Shared: board, create, reply and versioned retraction of this computer agent's own unanswered comments only; pull, resolve, reopen and deleting others' comments return 403 with advice to ask the owner. Runtime responses carry full threads projected as AgentComment, without member IDs, emails, people maps, you or owner identity; roles identify owner/participant/agent. Runtime writes appear as Agent; shared writes store an opaque computer author id for retraction and per-person thread limits, omitted from runtime responses. 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), and anyone signed out: a request with no credential at all (no Authorization header and no session cookie) reads a public computer's board as a signed-out visitor, without you, jobs or listener, and with each person named by their profile name or Someone, never an email or part of one; a private computer answers it 404. Send since, the revision you hold. When nothing changed since, the answer is {revision, changed:false, enabled, people, you, owner} without comments; otherwise comments holds every open and asked comment and the 50 comments finished last, with full threads. Human messages carry who as member:\<id>, resolved to a name in people; agent messages carry by:agent and agent (their name). The people map holds only you, the owner and the people who wrote on the board; people carry an email only on the owner's board. Reading a board records nothing about who read it. A computer with comments switched off answers enabled:false and no comments. A request with no Authorization header, signed in or signed out, spends its own allowance of 300 board reads a minute per IPv4 address or IPv6 /64, separate from the ordinary source and account allowances; the layer reads the board when a page is shown, so do not poll it faster than that. A session cookie that no longer signs anyone in is answered 401 and cleared, so the next read is a signed-out one. A site published without an account reads as enabled: false, until it is claimed, to everyone but its publisher's agent (claimKeyAuth) and the browser holding its comment link (commentLinkCookie); its stored switch is unchanged.

## 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.
- Claim \<claim_key>: the claim key a publish without an account returned. Until the computer is claimed or expires it authorizes further publishes to that computer, claiming it, and its publisher's agent on that computer's comments: the board, pull without a job, create (with ink), reply, resolve, reopen, delete and watch, with owner rights on that one site and identity-free answers like a computer's runtime token. Any other computer, a wrong key, or a claimed computer answers 404 computer_not_found; an expired one 409 claim_unavailable. Signed in after claiming, use a bearer and drop the claim key.
- Set by POST /api/computers/{id}/comment-link, from the comment link (comment_url) a publish without an account returned. While nobody has claimed the computer, the browser holding it reads that computer's board and creates, replies to and retracts its own comments as the link holder (guest:\<computer id>), from the web app's origin. It means nothing on a claimed computer.
- No credential: the request is also answered without one.

## 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.
- `since` (query, string): The revision you hold, from an earlier board.

## Responses

- `200`: The board.
  - `application/json` (CommentBoard or RuntimeCommentBoard)
    - CommentBoard
      - `revision` (string, required): Send it back as since. Empty when comments are off.
      - `changed` (boolean, required): False when the revision you sent is still current; comments is then absent.
      - `enabled` (boolean, required): False while comments are off for the computer.
      - `computer_id` (string, pattern `^cmp_[0-9a-f]{24}$`): The computer's immutable public id, present while comments are on. A client that asked by slug sends this id from then on, so a slug that moves to another computer cannot redirect what it writes.
      - `comments` (array of object): Present when changed: every open and asked comment and the 50 finished last.
        - `id` (string, required)
        - `state` ("open" or "asked" or "done", required): open waits for an agent to answer it, asked waits for the owner's answer, done is finished.
        - `version` (integer, at least 1, required): Changes on every update; send the one you read when resolving.
        - `release` (integer, required): Release the computer served when the comment was left; 0 when it served none.
        - `fixed_in_release` (integer): Release that fixed the comment, when a newer one was published.
        - `anchor` (object, required): Where on the page a comment points. An element anchor names its element by selector, and may leave out rect: the page finds the element. An area anchor needs rect unless it carries ink; with ink its selector is the first mark's el, and it may leave out rect too, since the page finds each mark's element. The page shows an anchor's pin by its drawn marks, then by the element its selector finds exactly once, then by its stored rect; with none of them it shows no pin.
          - `kind` ("element" or "area", required)
          - `page` (string, at most 500 characters, required): Path of the page, starting with /. The server stores it as the page's key, by the page rules of the comments contract that the page's comment script applies too: it is percent-encoded as a browser's location writes it (non-ASCII as UTF-8, hex in upper case, no escape decoded, so /café is stored as /caf%C3%A9), query parameters whose names hold a credential name are removed, path segments that look like tokens (a compact JWT, or a long run of URL-safe characters with a digit) become :token, a hash is kept only when it is a #/ or #! route (keyed the same way), and a key over maxLength keeps its path alone, without its query or hash. So /preview/\<token>?token=x&lang=en is stored as /preview/:token?lang=en.
          - `selector` (string, at most 300 characters): Selector the comment script made: steps of a tag, #id or [id="x"], up to two .classes, [data-testid="x"] and :nth-of-type(n), joined by " > ", at most 12 steps and maxLength bytes. Required for an element. For an area with ink it is the first mark's el, filled in when left out.
          - `text` (string): Text near the anchor; the server cuts it to 200 bytes.
          - `label` (string): Accessible label of the element; the server cuts it to 120 bytes.
          - `ink` (object): A drawing on the page, only on an area anchor: marks, each on one element and drawn relative to it, so a drawing lands in the same place on every screen. A mark is exactly one of path (strokes in the element's own box), shape (a named shape the page draws by hand) or write (words the page writes beside the element), with an optional color. A person's browser sends only paths, which also carry what it measured (on, start, end, line). At most 64000 bytes as JSON.
            - `marks` (array of object, 1 to 20 items, required)
              - `el` (string, 1 to 300 characters, required): Selector of the one element the mark is drawn on, in the same shape as an anchor's; html means the whole page (its full scroll size, so one unit is a thousandth of the page). A mark whose element the page does not find exactly once, or that is hidden or clipped away, is not drawn.
              - `shape` ("ring" or "box" or "underline" or "strike" or "cross"): A shape the page draws by hand to fit el's own text, in place of path and write: ring or box around it, underline, strike through it, cross over it. It is stored and read back by its name.
              - `write` (string, 1 to 160 characters): Words the page writes by hand beside el, in place of path and shape: at most 160 UTF-8 bytes on at most 3 lines split by \n, cleaned like a comment's text, in printable ASCII and £ € ← ↑ → ↓ ✓ ✗; a character the hand cannot write is refused.
              - `color` ("amber" or "blue" or "green" or "ink" or "purple" or "red"): The mark's colour; amber when left out, and then read back without one.
              - `path` (string, pattern `^M-?\d+ -?\d+(?: [ML]-?\d+ -?\d+)*$`, at most 4000 characters): The strokes in whole thousandths of el's border box: 0 is its left or top edge and 1000 its right or bottom, on each axis on its own, and a number below 0 or past 1000 is outside it, from -100000 to 100000. A move, then lines, a move for each stroke after the first. An underline: M0 1080 L1000 1080.
              - `on` (array of object, at most 3 items): Measured by a person's browser: elements under the mark, the most covered first.
                - `el` (string, at most 300 characters, required): Selector, in the same shape as an anchor's.
                - `text` (string): The element's text; the server cuts it to 60 bytes.
                - `ink` (integer, 1 to 100, required): Percent of the mark's samples on the element.
              - `start` (string, at most 300 characters): Measured by a person's browser: selector of the element under a line's first point.
              - `end` (string, at most 300 characters): Measured by a person's browser: selector of the element under a line's last point.
              - `line` ("through" or "under" or "around"): Measured by a person's browser: whether the mark runs through or under text, or around something.
              - Exactly one of: `path`, without `shape`, `write`; `shape`, without `path`, `write`, `on`, `start`, `end`, `line`; `write`, without `path`, `shape`, `on`, `start`, `end`, `line`
          - `picture` (object): Set by the server, never sent in an anchor: a drawing has a picture of what the person saw where they drew, a PNG of the page around their ink with the ink on it, as the client that sent it drew it. The server keeps the bytes as sent. The pull returns it under pictures with ?pictures=1.
            - `sha256` (string, pattern `^[0-9a-f]{64}$`, required): Hex SHA-256 of the PNG.
          - `rect` (object): A box in percent of the page, inside it.
            - `x` (number, 0 to 100, required)
            - `y` (number, 0 to 100, required)
            - `w` (number, 0 to 100, required)
            - `h` (number, 0 to 100, required)
          - `scroll_y` (number, 0 to 10000000): Scroll offset of the page in pixels when the comment was left.
          - `moment_ms` (integer, 0 to 86400000): On a page that plays a video: the moment in the video the comment was left at, in whole milliseconds from its start. Absent on a comment left at no moment, which is not the same as 0, the video's very start.
        - `thread` (array of object, required)
          - `by` ("owner" or "participant" or "agent", required): participant is a person other than the owner; agent is an agent, with owner or participant rights decided by the host.
          - `who` (string, pattern `^(member:[0-9]+|computer:.+)$`, at most 64 characters): A person is member:\<id>, resolved through the board people. A shared runtime agent is computer:\<id>, displayed by its agent name and retained for retraction and per-person thread limits. Absent for an owner-authorized agent.
          - `agent` (string, at most 64 characters): An agent's name, such as Operator or the MCP client's own name (Agent when it gave none or a reserved one). Absent for people, on an answer sent through the HTTP resolve route or the CLI, which name no agent, and on agent messages written before agents were named.
          - `resolved` ("done" or "asked"): On an agent's answer or the owner marking a comment done: the resulting state. A message without it, an agent's included, answers nothing.
          - `text` (string, required)
          - `files` (array of string): On an agent's answer only: the paths of the files it says it changed.
          - `request` (string, pattern `^[0-9a-f]{24}$`): On a comment's first message, a reply or an owner's answer whose client named it (CreateCommentRequest.request, ReplyCommentRequest.request, ReopenCommentRequest.request) only, so the same write sent again is stored once. Agents never read it.
          - `at` (string, date-time, required)
        - `created_at` (string, date-time, required)
        - `updated_at` (string, date-time, required)
      - `jobs` (array of object): Present when changed and a job exists: the owner's Asks still running and those settled in the last day, newest first.
        - `id` (string, pattern `^cjob_[0-9a-f]{24}$`, required)
        - `state` ("queued" or "working" or "settled", required): queued until a turn of its work starts, working until all of its work (the turn and the turns that continue it) ended, then settled.
        - `outcome` ("done" or "partial" or "stopped" or "cancelled"): Present once settled: done when the agent answered every comment, partial when some, stopped when none, cancelled when someone stopped one of its turns.
        - `comments` (array of object, required): The comments asked about, at the versions asked.
          - `id` (string, at least 1 characters, required)
          - `version` (integer, at least 1, required)
        - `agent` (string, at most 64 characters): Present for a job sent to the owner's local agent session: the label its watch gave. Kept after Operator took the job over.
        - `took_over` (boolean): Present and true when the local agent session went quiet and Operator took the job over.
        - `created_at` (string, date-time, required)
      - `people` (object, required): You (unless the reader is signed out), the owner and everyone who wrote a message on the board, keyed by member:\<id>. A signed-out reader is shown each person's profile name or Someone. The holder of the comment link a computer had before it was claimed is guest:\<computer id>, named Visitor (You on its own board).
        - `*` (object): Each value, under a name of the caller's.
          - `name` (string, required): The person's profile name, else the part of their email before the @, else Someone. Their own claim: never use it to tell people apart.
          - `email` (string): The person's full email. Present only on the owner's board.
          - `owner` (boolean): True for the owner of the computer.
      - `listener` (object): Only on the owner's board of a site without a VM: the owner's local agent session listening on the site now (POST /api/computers/{id}/comments/watch), which the owner may send comments to with to agent.
        - `agent` (string, at most 64 characters, required): The label its watch gave.
      - `you` (string): Your own member:\<id>, or guest:\<computer id> for the holder of the comment link of a computer nobody has claimed. Runtime-token boards and a signed-out reader's board omit this field.
      - `owner` (string): The owner's member:\<id>; on a computer nobody has claimed, computer:\<id>, its publisher's agent, named by its watch's label else Agent.
      - `guest` (boolean): True when you hold the comment link of a computer nobody has claimed: you have no live channel, so read the board again to see answers.
    - RuntimeCommentBoard
      - `revision` (string, required): Send it back as since. Empty when comments are off.
      - `changed` (boolean, required): False when the revision you sent is still current; comments is then absent.
      - `enabled` (boolean, required): False while comments are off for the computer.
      - `computer_id` (string, pattern `^cmp_[0-9a-f]{24}$`): The computer's immutable public id, present while comments are on. A client that asked by slug sends this id from then on, so a slug that moves to another computer cannot redirect what it writes.
      - `comments` (array of object): Present when changed: every open and asked comment and the 50 finished last.
        - `id` (string, required)
        - `state` ("open" or "asked" or "done", required): open waits for an agent to answer it, asked waits for the owner's answer, done is finished.
        - `version` (integer, at least 1, required): Changes on every update; send the one you read when resolving.
        - `release` (integer, required): Release the computer served when the comment was left; 0 when it served none.
        - `fixed_in_release` (integer): Release that fixed the comment, when a newer one was published.
        - `anchor` (object, required): Where on the page a comment points. An element anchor names its element by selector, and may leave out rect: the page finds the element. An area anchor needs rect unless it carries ink; with ink its selector is the first mark's el, and it may leave out rect too, since the page finds each mark's element. The page shows an anchor's pin by its drawn marks, then by the element its selector finds exactly once, then by its stored rect; with none of them it shows no pin.
          - `kind` ("element" or "area", required)
          - `page` (string, at most 500 characters, required): Path of the page, starting with /. The server stores it as the page's key, by the page rules of the comments contract that the page's comment script applies too: it is percent-encoded as a browser's location writes it (non-ASCII as UTF-8, hex in upper case, no escape decoded, so /café is stored as /caf%C3%A9), query parameters whose names hold a credential name are removed, path segments that look like tokens (a compact JWT, or a long run of URL-safe characters with a digit) become :token, a hash is kept only when it is a #/ or #! route (keyed the same way), and a key over maxLength keeps its path alone, without its query or hash. So /preview/\<token>?token=x&lang=en is stored as /preview/:token?lang=en.
          - `selector` (string, at most 300 characters): Selector the comment script made: steps of a tag, #id or [id="x"], up to two .classes, [data-testid="x"] and :nth-of-type(n), joined by " > ", at most 12 steps and maxLength bytes. Required for an element. For an area with ink it is the first mark's el, filled in when left out.
          - `text` (string): Text near the anchor; the server cuts it to 200 bytes.
          - `label` (string): Accessible label of the element; the server cuts it to 120 bytes.
          - `ink` (object): A drawing on the page, only on an area anchor: marks, each on one element and drawn relative to it, so a drawing lands in the same place on every screen. A mark is exactly one of path (strokes in the element's own box), shape (a named shape the page draws by hand) or write (words the page writes beside the element), with an optional color. A person's browser sends only paths, which also carry what it measured (on, start, end, line). At most 64000 bytes as JSON.
            - `marks` (array of object, 1 to 20 items, required)
              - `el` (string, 1 to 300 characters, required): Selector of the one element the mark is drawn on, in the same shape as an anchor's; html means the whole page (its full scroll size, so one unit is a thousandth of the page). A mark whose element the page does not find exactly once, or that is hidden or clipped away, is not drawn.
              - `shape` ("ring" or "box" or "underline" or "strike" or "cross"): A shape the page draws by hand to fit el's own text, in place of path and write: ring or box around it, underline, strike through it, cross over it. It is stored and read back by its name.
              - `write` (string, 1 to 160 characters): Words the page writes by hand beside el, in place of path and shape: at most 160 UTF-8 bytes on at most 3 lines split by \n, cleaned like a comment's text, in printable ASCII and £ € ← ↑ → ↓ ✓ ✗; a character the hand cannot write is refused.
              - `color` ("amber" or "blue" or "green" or "ink" or "purple" or "red"): The mark's colour; amber when left out, and then read back without one.
              - `path` (string, pattern `^M-?\d+ -?\d+(?: [ML]-?\d+ -?\d+)*$`, at most 4000 characters): The strokes in whole thousandths of el's border box: 0 is its left or top edge and 1000 its right or bottom, on each axis on its own, and a number below 0 or past 1000 is outside it, from -100000 to 100000. A move, then lines, a move for each stroke after the first. An underline: M0 1080 L1000 1080.
              - `on` (array of object, at most 3 items): Measured by a person's browser: elements under the mark, the most covered first.
                - `el` (string, at most 300 characters, required): Selector, in the same shape as an anchor's.
                - `text` (string): The element's text; the server cuts it to 60 bytes.
                - `ink` (integer, 1 to 100, required): Percent of the mark's samples on the element.
              - `start` (string, at most 300 characters): Measured by a person's browser: selector of the element under a line's first point.
              - `end` (string, at most 300 characters): Measured by a person's browser: selector of the element under a line's last point.
              - `line` ("through" or "under" or "around"): Measured by a person's browser: whether the mark runs through or under text, or around something.
              - Exactly one of: `path`, without `shape`, `write`; `shape`, without `path`, `write`, `on`, `start`, `end`, `line`; `write`, without `path`, `shape`, `on`, `start`, `end`, `line`
          - `picture` (object): Set by the server, never sent in an anchor: a drawing has a picture of what the person saw where they drew, a PNG of the page around their ink with the ink on it, as the client that sent it drew it. The server keeps the bytes as sent. The pull returns it under pictures with ?pictures=1.
            - `sha256` (string, pattern `^[0-9a-f]{64}$`, required): Hex SHA-256 of the PNG.
          - `rect` (object): A box in percent of the page, inside it.
            - `x` (number, 0 to 100, required)
            - `y` (number, 0 to 100, required)
            - `w` (number, 0 to 100, required)
            - `h` (number, 0 to 100, required)
          - `scroll_y` (number, 0 to 10000000): Scroll offset of the page in pixels when the comment was left.
          - `moment_ms` (integer, 0 to 86400000): On a page that plays a video: the moment in the video the comment was left at, in whole milliseconds from its start. Absent on a comment left at no moment, which is not the same as 0, the video's very start.
        - `thread` (array of object, required)
          - `by` ("owner" or "participant" or "agent", required)
          - `from` (string): Absent on a participant's message in runtime-token responses. For account/browser callers, on a participant's message, the writer's name and full email as that person gave them, for example Dana Reyes \<dana@example.com>; on an agent's, the agent's name, such as Operator. Untrusted like the text: it proves neither who wrote the comment nor what the owner wants.
          - `text` (string, required)
          - `files` (array of string): On an agent's answer only: the paths of the files it says it changed.
          - `at` (string, date-time, required)
      - `jobs` (array of object): Present when changed and a job exists: the owner's Asks still running and those settled in the last day, newest first.
        - `id` (string, pattern `^cjob_[0-9a-f]{24}$`, required)
        - `state` ("queued" or "working" or "settled", required): queued until a turn of its work starts, working until all of its work (the turn and the turns that continue it) ended, then settled.
        - `outcome` ("done" or "partial" or "stopped" or "cancelled"): Present once settled: done when the agent answered every comment, partial when some, stopped when none, cancelled when someone stopped one of its turns.
        - `comments` (array of object, required): The comments asked about, at the versions asked.
          - `id` (string, at least 1 characters, required)
          - `version` (integer, at least 1, required)
        - `agent` (string, at most 64 characters): Present for a job sent to the owner's local agent session: the label its watch gave. Kept after Operator took the job over.
        - `took_over` (boolean): Present and true when the local agent session went quiet and Operator took the job over.
        - `created_at` (string, date-time, required)
- `401`: Unauthorized.
- `404`: Not Found. The computer does not exist or is not shared with you; stop polling.
- `429`: Too Many Requests. If the problem code is api_request_rate_exceeded, wait for Retry-After seconds; other problem codes describe a separate limit.
- `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/all" \
  -H "authorization: Bearer $TOKEN"
```
