---
title: "Ask the agent about comments"
description: "The account's owner only, from the site's page. Hands any number of open comments, each at the version the owner saw, to the owner's agent as one job: with to operator (the default), done by one…"
canonical: "https://www.cool.computer/docs/api-reference/comments/ask-the-agent-about-comments"
---
# Ask the agent about comments

> The account's owner only, from the site's page. Hands any number of open comments, each at the version the owner saw, to the owner's agent as one job: with to operator (the default), done by one…

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

The account's owner only, from the site's page. Hands any number of open comments, each at the version the owner saw, to the owner's agent as one job: with to operator (the default), done by one operator turn in the site's conversation; with to agent, sent to the owner's local agent session listening on the site (the board's listener), which claims it by pulling it within 2 minutes and keeps it while it renews it at least every 20 minutes (only its comment pull, board, create, reply, resolve and changes to the site's files or releases renew it; pull the job again during long work), else Operator takes it over. Asking changes no comment. A comment an unsettled job already holds is refused with `already_asked`; an asked comment needs the owner's answer first.

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

## Request body

Required.

- `application/json` (object)
  - `comments` (array of object, at least 1 items, required): Open comments, each at the version you saw, that no running job holds.
    - `id` (string, at least 1 characters, required)
    - `version` (integer, at least 1, required)
  - `to` ("operator" or "agent", default "operator"): Who does the job: Operator, or the owner's local agent session the board names as listener.
  - `agent` (string, at most 64 characters): With to agent, and only then: the board's listener.agent, the agent the owner was shown. A different agent listening now, or none, is 409 agent_not_listening.

## Responses

- `201`: The job.
  - `application/json` (object)
    - `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)
- `400`: Bad Request. `invalid_comment`: ask about at least one open comment, each once, with the version you saw, and send agent exactly when to is agent.
- `401`: Unauthorized.
- `403`: Forbidden. `not_your_comment`: only the site's owner can ask the agent.
- `404`: Not Found. `comments_off`: comments are off for the computer. `comment_not_found`: a comment was deleted; read the board again.
- `409`: Conflict. `comment_changed`: a comment changed since you saw it; read the board again. `already_asked`: the agent is already working on a comment. `agent_not_listening`: to agent, but the agent named is not the one listening on the site (or none is), or the site has a VM; read the board again, or send it to Operator.
- `429`: Too Many Requests. `agent_busy`: the agent already has as many turns waiting as it takes; nothing was queued, so wait for some of its queued work to finish, then ask again. `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/ask" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  --data '{"comments":[{"id":"string","version":1}]}'
```
