Add Comment

Use the createComment mutation to post a comment on a record. Comments accept rich HTML content, file attachments, and @mentions, and can be posted as threaded replies to an existing comment. Each comment is added to the record’s activity feed and triggers the relevant notifications, subscriptions, and webhooks. Records are Record objects in the API.

The same mutation comments on a record (category: TODO), a discussion (category: DISCUSSION), or a status update (category: STATUS_UPDATE); this page focuses on commenting on records.

Request

The smallest call posts a comment on one record. Pass the record ID as categoryId with category: TODO, and supply both the rendered html and a plain-text text fallback.

mutation AddComment {
  createComment(
    input: {
      category: TODO
      categoryId: "todo_123"
      html: "<p>This task is progressing well.</p>"
      text: "This task is progressing well."
    }
  ) {
    id
    html
    createdAt
    user {
      id
      fullName
    }
  }
}

Parameters

CreateCommentInput

CommentCategory

Response

{
  "data": {
    "createComment": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "html": "<p>This task is progressing well.</p>",
      "createdAt": "2026-05-29T14:03:11.000Z",
      "user": {
        "id": "clm4n8qwx000108l0d2k1abcd",
        "fullName": "Ada Lovelace"
      }
    }
  }
}

Returns

createComment returns the created Comment.

Full example

Post a richly formatted comment as a threaded reply, and read back the threading and reaction fields:

mutation AddReply {
  createComment(
    input: {
      category: TODO
      categoryId: "todo_123"
      parentId: "comment_123"
      tiptap: true
      html: "<p>Agreed — here is my <strong>feedback</strong>:</p><ul><li>Great progress on the design</li><li>Need to review the API integration</li></ul>"
      text: "Agreed — here is my feedback: - Great progress on the design - Need to review the API integration"
    }
  ) {
    id
    html
    createdAt
    parentId
    replyCount
    reactions {
      emoji
      count
      reactedByMe
    }
    user {
      id
      fullName
      image {
        thumbnail
        small
      }
    }
  }
}

File attachments

To attach an uploaded file so it renders as a clickable attachment (the same way files appear when attached in the Blue UI), embed it as a <div> in the html field and set tiptap: true. Without tiptap: true, the attachment markup is stripped by sanitization.

Step 1 — Upload the file

Upload the file with the uploadFile mutation to get its metadata (uid, name, size, type, extension).

Step 2 — Embed the attachment

Each attachment is a <div> carrying a JSON file attribute:

<div
  class="attachment"
  file='{"uid":"FILE_UID","name":"FILENAME","size":SIZE_IN_BYTES,"type":"MIME_TYPE","extension":"EXT"}'
></div>

Step 3 — Post the comment

mutation AddCommentWithFile {
  createComment(
    input: {
      category: TODO
      categoryId: "todo_123"
      tiptap: true
      html: "<p>Here is the report.</p><div class=\"attachment\" file='{\"uid\":\"cm8qujq3b01p22lrv9xbb2q62\",\"name\":\"report.pdf\",\"size\":204800,\"type\":\"application/pdf\",\"extension\":\"pdf\"}'></div>"
      text: "Here is the report."
    }
  ) {
    id
    html
    createdAt
  }
}

For an end-to-end walkthrough (upload + comment, with Python), see Attaching files to comments. Once uploaded, a file’s download URL is https://api.blue.app/uploads/{uid}/{url_encoded_filename} — see File URLs for thumbnail and inline variants.

Errors

{
  "errors": [
    {
      "message": "You don't have permission to perform this action.",
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

Permissions

Any workspace member can comment on a record except those with VIEW_ONLY access. A custom role that has records disabled (isRecordsEnabled: false) cannot comment, and no one can comment on a record in an archived workspace.

Related

• List records
• Manage record assignees
• Tags
• Upload files