Add Comment

Add Comment

The createComment mutation allows you to add comments to records in Blue. Comments support rich HTML content, file attachments, @mentions, and are automatically integrated with the activity feed and notification system.

Basic Example

Add a simple text comment to a record:

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

Advanced Example

Add a comment with rich formatting, images, and TipTap editor processing:

mutation AddCommentAdvanced {
  createComment(
    input: {
      html: "<p>Here's my <strong>feedback</strong> on this task:</p><ul><li>Great progress on the design</li><li>Need to review the API integration</li></ul><p>Attaching screenshot:</p><img src='data:image/png;base64,iVBOR...' />"
      text: "Here's my feedback on this task: - Great progress on the design - Need to review the API integration Attaching screenshot:"
      category: TODO
      categoryId: "clm4n8qwx000008l0g4oxdqn7"
      tiptap: true
    }
  ) {
    id
    html
    text
    createdAt
    user {
      id
      name
      avatar
    }
    activity {
      id
    }
    isRead
    isSeen
  }
}

Input Parameters

CreateCommentInput

CommentCategory Values

Response Fields

The mutation returns a Comment object with comprehensive details:

Required Permissions

Users must have appropriate project access to comment on records:

Important: The user must be a member of the project that contains the record and must NOT have VIEW_ONLY access level.

Error Responses

UnauthorizedError

{
  "errors": [{
    "message": "You don't have permission to comment on this record",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

When: User lacks permission to comment on the specified record/entity.

ValidationError

{
  "errors": [{
    "message": "Invalid input parameters",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

When: Required fields are missing or contain invalid data.

CommentNotFoundError

{
  "errors": [{
    "message": "Record not found",
    "extensions": {
      "code": "COMMENT_NOT_FOUND"
    }
  }]
}

When: The specified categoryId doesn’t correspond to an existing record.

UserInputError

{
  "errors": [{
    "message": "Content validation failed",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

When: HTML content fails sanitization or contains malicious code.

File Attachments

To include uploaded files as clickable attachments in a comment (the same way files appear when attached via the Blue UI), embed them as <div> elements in the html field. You must set tiptap: true for the API to parse and link the files.

Step 1: Upload the File

Upload your file using the uploadFile mutation first to get the file metadata (uid, name, size, type, extension).

Step 2: Embed the Attachment in the Comment HTML

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

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

Example

mutation AddCommentWithFile {
  createComment(
    input: {
      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."
      category: TODO
      categoryId: "clm4n8qwx000008l0g4oxdqn7"
      tiptap: true
    }
  ) {
    id
    html
    createdAt
  }
}

For a complete example with file upload + comment creation (including Python code), see the Attaching Files to Comments section in the upload guide.

File Download URLs

Once a file is uploaded, its download URL is:

https://api.blue.cc/uploads/{uid}/{url_encoded_filename}

See the File URLs section for all URL variants (thumbnails, inline display).

Important Notes

Content Processing

• HTML Sanitization: All HTML content is automatically sanitized to prevent XSS attacks
• File Extraction: When tiptap: true, attachment <div> elements in the HTML are parsed and the referenced files are linked to the comment in the database
• TipTap Mode: When tiptap: true, uses specialized sanitization that supports file attachment parsing
• @Mentions: User mentions in comments are automatically processed and trigger notifications

Performance Considerations

• Comments are indexed for search automatically
• Large image attachments are processed asynchronously
• Each comment creates an activity record for the project timeline

Side Effects

Adding a comment triggers several automated processes:

• Activity Creation: Creates an activity record visible in project timeline
• Search Indexing: Comment content is added to the project search index
• Notifications: Sends email, push, and in-app notifications to relevant users
• Real-time Updates: Publishes comment to GraphQL subscriptions for live updates
• Webhooks: Triggers external webhook if configured for the project
• @Mention Processing: Processes user mentions and sends targeted notifications
• File Processing: Extracts and processes any embedded images or files from HTML content

Content Security

• All HTML is sanitized using industry-standard libraries
• File uploads are validated for type and size
• Malicious content is automatically stripped
• User-generated content is escaped properly in all contexts

Integration Features

• Activity Feed: Comments appear in the project activity timeline
• Search: Comment content is searchable within the project
• Notifications: Configurable notification preferences for different comment types
• Real-time: Comments appear instantly for other users viewing the same record
• Mobile Support: Comments are fully supported in mobile applications

Related Endpoints

• List Comments: Query comments to retrieve existing comments on records
• Update Comment: Modify existing comment content
• Delete Comment: Remove comments with proper authorization
• List Records: Query todos to find records that can be commented on