---
title: "/discussions/:discussionId/comments"
method: POST
path: "/v1/discussions/{discussionId}/comments"
tags: ["Discussions"]
---

# /discussions/:discussionId/comments

`POST /v1/discussions/{discussionId}/comments`

## Request

- Base URL: `api.air.inc` (relative, and the document’s source URL is not known)
- URL: `api.air.inc/v1/discussions/{discussionId}/comments`
- Auth: one of:
  - API key in header `x-api-key` and API key in header `x-air-workspace-id`
  - HTTP bearer and API key in header `x-air-workspace-id`
- TypeScript: <https://skmtc.dev/air/apis/air-api/docs/v1/discussions/:discussionId/comments/post.ts> (a function with typed inputs; its response is checked against the schema)

Add a comment to a discussion.

The body rules match `POST /v1/discussions`: plain text, 1 to 500
characters as sent, `{{mention:N}}` placeholders, and no raw mention
tokens. A mentioned person who cannot view the discussion is not
notified, and the reply still succeeds.

A timeout can create a duplicate. List the discussion's comments
before retrying.

`updatedAt` equals `createdAt` until the comment is edited. Callers
detect an edit with `updatedAt !== createdAt`.

Requires the `comments.write` OAuth scope.

## Request body

- CommentWriteRequest
  - `body` string, required
  - `mentions` MentionInput[], nullable: Required on edit when the comment already has mentions: omitting it or sending `null` is 409. An empty array removes them. On a reply, `null` is the same as no mentions.
    - `accountId` string, uuid, required

## Response `201`

Comment created

- DiscussionComment
  - `id` string, uuid, required
  - `discussionId` string, uuid, required
  - `body` string, required: Plain text with mentions rendered as `@Display Name`. Escape this before rendering HTML.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required: Equal to `createdAt` until the first edit that changes the stored text. An edit is `updatedAt !== createdAt`.
  - `author` DiscussionAuthor, required
    - `type` 'workspace_account' | 'anonymous', required
    - `id` string, uuid: Present when `type` is `workspace_account`. The account id.
    - `displayName` string, nullable, required
  - `mentions` DiscussionMention[], required
    - `id` string, uuid, required: Account id. The same id as `GET /v1/members` `id`.
    - `displayName` string, nullable, required

## Other responses

- `400`: Invalid body or mentions
- `403`: You cannot manage discussions on this asset
- `404`: Discussion not found

## Changes

- **2026-11-03** `8e6005b272a1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/air/apis/air-api/changes/v1/discussions/:discussionId/comments/post.md)

---

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