---
title: "Leave a comment"
method: POST
path: "/reports/{id}/comments"
tags: ["Comments"]
---

# Leave a comment

`POST /reports/{id}/comments`

## Request

- Base URL: `https://commareports.com/api/v1`
- URL: `https://commareports.com/api/v1/reports/{id}/comments`
- Auth: HTTP bearer

Create a top-level comment, optionally anchored to a text range (`anchor_text` + `anchor_prefix`/`anchor_suffix`) or a block (`block_id`). Requires comment access on the report (`can_comment_report`) — 403 otherwise. Fires `comment.created` (and `comment.mentioned` per unique @handle) webhooks. Scope: `comments:write`.

## Request body

- CommentCreateRequest
  - `body` string, required
  - `block_id` string: Anchor to a block element id.
  - `anchor_text` string: Exact text the comment anchors to.
  - `anchor_prefix` string: Disambiguating text before the anchor.
  - `anchor_suffix` string: Disambiguating text after the anchor.

## Response `201`

Comment created.

- CommentCreated
  - `id` string, uuid, required
  - `body` string, required
  - `status` 'open' | 'resolved', required
  - `created_at` string, date-time, required

## Other responses

- `400`: Malformed body or invalid field.
- `401`: Missing, invalid, revoked, or expired token.
- `403`: Token missing the required scope, or no access to the resource.
- `429`: Rate limit exceeded. Rate limit: per-token sliding window (plan-aware — Free 60 req/min, Pro 600, Team/Enterprise 6000 by default); 429 responses carry a Retry-After header.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/commareports/apis/comma-api.md) · [All operations](https://skmtc.dev/commareports/apis/comma-api/llms.txt) · [OpenAPI document](https://skmtc.dev/commareports/apis/comma-api/revisions/cd5263522ade?raw)