AIair
Discussions

/discussions

Changed on

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.

get/v1/discussions

Request

  • Base URL
    api.air.inc (relative, and the document’s source URL is not known)
  • Auth
    • API key in header x-api-key and API key in header x-air-workspace-id
    • or HTTP bearer and API key in header x-air-workspace-id
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

Query parameters

assetIdstring uuid

Discussions on this asset. Required unless boardId is set. Cannot be combined with boardId.

assetVersionIdstring uuid

Limit the asset list to this version. Requires assetId. The current version is coverVersion.id on GET /v1/assets/{assetId}.

boardIdstring uuid

Discussions on assets currently on this board. Required unless assetId is set. Cannot be combined with assetId. A missing or trashed board is 404.

resolved'true' | 'false'

When true or false, only discussions in that state.

sortBy'lastCommentedAt' | 'createdAt'

lastCommentedAt (default) or createdAt. createdAt is the time of the first comment and does not move when someone replies.

sortDirection'asc' | 'desc'

desc (default) or asc.

limitstring

Page size. Default 12, maximum 100.

cursorstring

Cursor from the previous page. It must match the same filters and sort. It points at the first discussion of the next page, so pages don't overlap.

Response

Discussions listed

totalinteger required

Example response

{
  "data": [
    {
      "annotations": [
        {
          "color": "#ffd1dc"
        }
      ]
    }
  ]
}

Changes