---
title: "/discussions"
method: POST
path: "/v1/discussions"
tags: ["Discussions"]
---

# /discussions

`POST /v1/discussions`

## Request

- Base URL: `api.air.inc` (relative, and the document’s source URL is not known)
- URL: `api.air.inc/v1/discussions`
- 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/post.ts> (a function with typed inputs; its response is checked against the schema)

Start a discussion on an asset version.

`assetVersionId` is required. There is no default to the current
version. The current version is `coverVersion.id` on
`GET /v1/assets/{assetId}`.

The body has no board. A `boardId` in the body is ignored. In a
workspace that scopes comments to boards, a discussion with no board
needs `asset.canManageDiscussions` at the workspace level, so a board
guest gets 403 here even when they can comment in their board.

`body` is plain text, 1 to 500 characters counted as sent (one emoji
is one character). A whitespace-only body is rejected. Mention someone
with `{{mention:N}}` and a `mentions` entry at that index. Names are
filled in by the server. At most 10 mentions, each `accountId` once,
and every entry must appear in the body. A raw `@[Name](accountId)`
token is rejected. A mentioned person who cannot view the discussion
is not notified, and the create still succeeds.

`annotations` is optional, at most 10. `color` is `#RRGGBB`, six hex
digits, either case. `#ffd1dc` is valid. Box coordinates and
dimensions, and pencil points, are fractions of the frame from 0 to 1.
A pencil annotation has 1 to 10 lines, and each line has 2 to 1000
points. On a document or PDF, every box and every pencil line needs a
`pageNumber`.

A timeout can create a duplicate. List the asset's discussions before
retrying.

Returns the discussion with its first comment. `updatedAt` equals
`createdAt` until that comment is edited.

Requires the `comments.write` OAuth scope.

## Request body

- CreateDiscussionRequest
  - `assetId` string, uuid, required
  - `assetVersionId` string, uuid, required
  - `body` string, required
  - `mentions` MentionInput[], nullable
    - `accountId` string, uuid, required
  - `annotations` DiscussionAnnotationInput[]
    - union: An annotation sent on `POST /v1/discussions`.
      - BoxAnnotationInput
        - `type` 'box', required
        - `timestamp` number: Seconds into a video. Omit for a still image.
        - `endTimestamp` number: Requires `timestamp`, and must be greater than or equal to it.
        - `coordinates` object, required: Top-left corner as fractions of the frame.
          - `x` number, required
          - `y` number, required
        - `dimensions` object, required: Width and height as fractions of the frame. The box must fit in the frame.
          - `width` number, required
          - `height` number, required
        - `color` string, required: `#RRGGBB`, either case.
        - `pageNumber` integer: Document page, from 1. Required on a document or PDF. Omit for an image or video.
      - PencilAnnotationInput
        - `type` 'pencil', required
        - `timestamp` number: Seconds into a video. Omit for a still image.
        - `endTimestamp` number: Requires `timestamp`, and must be greater than or equal to it.
        - `lines` object[], required
          - `coordinates` object[], required
            - `x` number, required
            - `y` number, required
          - `lineWidth` number, required
          - `color` string, required: `#RRGGBB`, either case.
          - `pageNumber` integer: Document page, from 1. Required on a document or PDF. Omit for an image or video.

## Response `201`

Discussion created

- Discussion
  - `id` string, uuid, required
  - `resolved` boolean, required
  - `createdAt` string, date-time, nullable, required: When the first comment was created.
  - `lastCommentedAt` string, date-time, nullable, required: When the latest comment was created. A reply moves this.
  - `asset` object, required
    - `id` string, uuid, required
  - `assetVersion` object, required
    - `id` string, uuid, required: The asset version id. This is `assetVersionId` on create.
    - `version` integer, required
  - `boardId` string, uuid: Present only when the discussion has an active stored board and the caller can view that board. Otherwise the field is omitted.
  - `annotations` DiscussionAnnotation[], required
    - union: An annotation as stored. Annotations saved outside the public API may fall outside the limits on `DiscussionAnnotationInput`, so this schema only states what every read guarantees.
      - BoxAnnotation
        - `type` 'box', required
        - `timestamp` number: Seconds into a video. Omitted for a still image.
        - `endTimestamp` number: End of the time range in seconds, when one was saved.
        - `coordinates` object, required: Top-left corner as fractions of the frame.
          - `x` number, required
          - `y` number, required
        - `dimensions` object, required: Width and height as fractions of the frame.
          - `width` number, required
          - `height` number, required
        - `color` string, required: `#RRGGBB` when created through this API. An annotation saved elsewhere may use another color format.
        - `pageNumber` integer: Document page, from 1. Omitted for an image or video.
      - PencilAnnotation
        - `type` 'pencil', required
        - `timestamp` number: Seconds into a video. Omitted for a still image.
        - `endTimestamp` number: End of the time range in seconds, when one was saved.
        - `lines` object[], required
          - `coordinates` object[], required: Points as fractions of the frame. A stored line may have a single point.
            - `x` number, required
            - `y` number, required
          - `lineWidth` number, required
          - `color` string, required: `#RRGGBB` when created through this API. An annotation saved elsewhere may use another color format.
          - `pageNumber` integer: Document page, from 1. Omitted for an image or video.
  - `comments` CommentList, required
    - `data` DiscussionComment[], required
      - `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
    - `pagination` CursorPage, required
      - `hasMore` boolean, required
      - `cursor` string, nullable, required: Present when `hasMore` is true. Send it as the next `cursor`.
    - `total` integer, required

## Other responses

- `400`: Invalid body, mentions, version, or annotation
- `403`: You cannot manage discussions on this asset. In a workspace that scopes comments to boards, you also need that permission at the workspace level.
- `404`: Asset or version not found

## Changes

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

[Operation history](https://skmtc.dev/air/apis/air-api/changes/v1/discussions/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)