AIair
Discussions

/discussions

Changed on

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.

post/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.

Request body

assetIdstring uuid required
assetVersionIdstring uuid required
bodystring required

Example request

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

Response

Discussion created

idstring uuid required
resolvedboolean required
createdAtstring date-time nullable required

When the first comment was created.

lastCommentedAtstring date-time nullable required

When the latest comment was created. A reply moves this.

boardIdstring uuid

Present only when the discussion has an active stored board and the caller can view that board. Otherwise the field is omitted.

Example response

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

Changes