Skip to main content
POST
Create computer comment

Authorizations

Authorization
string
header
required

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.

Path Parameters

id
string
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.

Minimum string length: 1
Example:

"agent-atlas"

Body

application/json
text
string
required

What should change, at most maxLength bytes. May be empty when the anchor carries ink: a drawing says what to change without words.

Maximum string length: 1000
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.

request
string

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.

Pattern: ^[0-9a-f]{24}$
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

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.

Maximum string length: 64

Response

The new comment.

id
string
required
Example:

"comment_1a2b3c"

state
enum<string>
required

open waits for an agent to answer it, asked waits for the owner's answer, done is finished.

Available options:
open,
asked,
done
version
integer
required

Changes on every update; send the one you read when resolving.

Required range: x >= 1
release
integer
required

Release the computer served when the comment was left; 0 when it served none.

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.

thread
object[]
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
fixed_in_release
integer

Release that fixed the comment, when a newer one was published.