---
title: "Create computer comment"
description: "Also accepts this computer's own runtime token, with the computer named by its name or id; a different computer returns 404."
canonical: "https://www.cool.computer/docs/api-reference/comments/create-computer-comment"
---
# Create computer comment

> Also accepts this computer's own runtime token, with the computer named by its name or id; a different computer returns 404.

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

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). Leaves a comment on a page of the computer's site, anchored to an element or an area. Text is cleaned and must be 1 byte up to the text's maxLength in CreateCommentRequest, and may be empty for a drawing. The owner's agents read it with the pull; the owner hands it to Operator with POST /api/computers/{id}/comments/ask. An agent with the owner's credential leaves a comment the same way (the MCP tool cool_leave_comment), naming itself in agent so the comment is the agent's, not the owner's: an element anchor with only page and selector, rect left out, or a drawing: an area anchor with page and ink.marks, each mark an element's el and one of a path in that element's own box, a named shape or words to write (see CommentInk), selector and rect left out, or a part of the page: an area anchor with page and rect (the tool's area), selector and ink left out. A computer holds any number of comments. Anyone but the owner and the people the computer is shared with may make 10 writes a minute on one computer, and together 60 new comments an hour.

## 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.

## 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.

## Request body

Required.

- `application/json` (object)
  - `request` (string, pattern `^[0-9a-f]{24}$`): An id the client gives this create, new for each comment, and sends again with the same create when the answer was lost: a comment you already left with that request, the same text and the same anchor is the answer (201) and nothing is stored, and other text or another anchor under it is 400 invalid_comment: send new words with a new request. The server always chooses the comment's id. Leave it out to always leave a new comment.
  - `text` (string, at most 1000 characters, required): What should change, at most maxLength bytes. May be empty when the anchor carries ink: a drawing says what to change without words.
  - `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.
  - `picture` (string): Only with an anchor that carries ink: what the person saw where they drew, a PNG of at most 1500000 bytes and 2000 pixels a side. The server keeps it as sent, so the client blanks what must not be shown (password fields) before sending it, and sets the anchor's picture; an anchor's own picture is ignored.
  - `agent` (string, at most 64 characters): Your name, such as Codex, when you are an agent leaving this comment with the owner's own credential (cool comments leave sends it): the comment is then that agent's, not the owner's, and its name is shown on the comment and the page's pen. Left out or empty, the comment is the credential's own, as without it. Cleaned and cut to maxLength bytes; a name that cleans to nothing, or could pass for Operator, the owner or Cool Computers (spacing and surrounding punctuation aside), shows as Agent. Ignored for anyone else, the computer's own runtime token included: their comment is theirs.

## Responses

- `201`: The new comment.
  - `application/json` (Comment or AgentComment)
    - Comment
      - `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)
    - AgentComment
      - `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)
- `400`: Bad Request. `invalid_comment`: fix the comment or its anchor and send it again.
- `401`: Unauthorized.
- `404`: Not Found. `comments_off`: comments are off for the computer; ask the owner to turn them on, or, as the owner, PUT /api/computers/{id}/comment-settings. `comment_not_found`: read the comments again, the comment may have been deleted or retracted. The computer itself is also 404 for anyone it is not shared with when it is private.
- `413`: Request Entity Too Large. `comment_too_large`: shorten the comment.
- `429`: Too Many Requests. `comment_rate_exceeded`: anyone but the owner and the people the computer is shared with may make 10 comments, replies and retractions a minute on one computer; wait for Retry-After seconds and send it again, nothing was saved. `comment_site_rate_exceeded`: anyone but the owner and the people the computer is shared with may create 60 comments an hour on one computer, all together; wait for Retry-After seconds and send it again, nothing was saved. `api_request_rate_exceeded`: the account request limit; 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 -X POST "https://api.cool.computer/api/computers/$PARAM_ID/comments" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  --data '{"text":"string","anchor":{"kind":"element","page":"/menu","selector":"section > a.cta"}}'
```
