---
title: "Comment on an issue"
method: POST
path: "/v1/issues/{idOrNumber}/comments"
tags: ["Issues"]
---

# Comment on an issue

`POST /v1/issues/{idOrNumber}/comments`

## Request

- Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.grepr.ai/v1/issues/{idOrNumber}/comments`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Posts a comment, on an open or closed issue. A person may make it guidance, advice every later investigation on the issue's entities weighs.

## Path parameters

- `idOrNumber` string, required

## Request body

- PostIssueCommentRequest: Posts a comment on an issue. Comments are allowed on closed issues too, so a person can leave guidance on an issue they closed as `IGNORED`.
  - `body` string, required: The markdown body.
  - `guidance` boolean: Makes it guidance, advice every later investigation on the issue's entities weighs; people only.
  - `lockedFieldProposal` string: The locked field the comment proposes changing, named as in a `FIELD_LOCKED` error: a field such as `priority`, or `label:<label>`.
  - `version` integer: The version the comment was written against; a stale one is rejected with 409 and the current issue. Null posts against whatever is current.

## Response `200`

Comment posted

- IssueComment: A comment on an issue. A guidance comment, which only people write, is advice every later investigation on the issue's entities weighs; any other comment is a plain note.
  - `author` IssueActor: Who made a change to an issue. An agent is named by its own id and the investigation it acted in, never by the service account it authenticated as, since several agents may share one.
    - `agentId` string: The agent, for an agent actor; null otherwise.
    - `id` string: The person's user id, the agent's execution principal (its service account's token subject), or `system` for the server.
    - `investigationId` string: The investigation the agent acted in, for an agent actor; null otherwise.
    - `kind` 'PERSON' | 'AGENT' | 'SYSTEM': A person, an agent, or the server.
  - `body` string: The markdown body.
  - `channel` 'REST' | 'MCP' | 'SYSTEM': How a change reached the server.
  - `createdAt` string, date-time: When it was written.
  - `editedAt` string, date-time: When its author last changed the body, or null.
  - `guidance` boolean: Whether it is guidance, which agents weigh as advice.
  - `guidanceSetAt` string, date-time: When it was marked guidance, or null.
  - `guidanceSetBy` string: The user id of the person who marked it guidance, or null.
  - `id` string: The comment id.
  - `issueId` string: The issue it is on.
  - `lockedFieldProposal` string: The locked field the comment proposes changing, as named in a `FIELD_LOCKED` error (`priority`, `label:cost`), or null.

## Other responses

- `400`: Guidance from an agent, or a bad proposal
- `401`: Unauthorized
- `403`: No permission to edit the issue
- `404`: Issue not found
- `409`: Stale version; the body carries the current issue

---

[API](https://skmtc.dev/grepr/apis/grepr-api.md) - [All operations](https://skmtc.dev/grepr/apis/grepr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grepr/apis/grepr-api/revisions/2a5ce03a0bf0?raw)