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

# /discussions

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

List discussions on an asset or on the assets currently in a board.

One of `assetId` or `boardId` is required. They cannot be combined.
Each discussion includes at most 10 comments, oldest first. When
`comments.pagination.hasMore` is true, pass `comments.pagination.cursor`
to `GET /v1/discussions/{discussionId}/comments`.

**Sort.** Default is `sortBy=lastCommentedAt&sortDirection=desc`. Pages
don't overlap. With the default `lastCommentedAt` sort, a reply between
pages can move a discussion, so it may repeat or be skipped. For a
stable walk, use `sortBy=createdAt&sortDirection=asc`: `createdAt` is
the first comment and does not move, and a discussion started while
you page sorts after the cursor and still shows up. With
`sortDirection=desc`, a discussion started after your first page sorts
before the cursor and is missed until you list from the beginning.

**Boards.** In a workspace that does not scope comments to boards,
`?boardId=` returns every discussion on assets currently on that board,
including discussions started on another board. Discussions that are
visible on those assets but were not returned are listed with
`?assetId=` per asset. In a workspace that scopes comments to boards,
`?boardId=` returns only discussions stored on that board, and
`?assetId=` without `boardId` returns discussions with no board. That
no-board list is empty unless the caller has `asset.canViewDiscussions`
on both the asset and the workspace.

`boardId` on a discussion is present only when the stored board is
still active and the caller can view it. A trashed stored board is
omitted: the discussion stays on an asset list in an unscoped
workspace, and it is not part of the no-board asset list in a scoped
workspace. Permanently deleting a board deletes discussions created in
it, including ones that were visible on the asset in an unscoped
workspace.

Comment `body` is user-generated. Escape it before rendering HTML.
`mentions` is parsed from the stored text. `id` there is the same
account id as `author.id` for a workspace account and as `id` on
`GET /v1/members`.

Requires the `comments.read` OAuth scope.

## Query parameters

- `assetId` string, uuid
- `assetVersionId` string, uuid
- `boardId` string, uuid
- `resolved` 'true' | 'false'
- `sortBy` 'lastCommentedAt' | 'createdAt'
- `sortDirection` 'asc' | 'desc'
- `limit` string
- `cursor` string

## Response `200`

Discussions listed

- DiscussionList
  - `data` Discussion[], required
    - `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.
              - …
            - `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
  - `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 filters, sort, or cursor
- `403`: You cannot view discussions for this asset or board
- `404`: Asset, version, or board not found

## Changes

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

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