Comments

The Comments API lets your integrations post and read internal team discussion on any commentable entity in your workspace. Comments are not customer-facing -- they show up in the dashboard's activity panel for the parent entity, alongside the @mentions, replies, and notifications your team already gets when collaborating in BlueSuite.

A single namespace, /api/v1/comments, handles comments for every supported entity. You specify the parent entity by passing module_type and module_id.

Authentication

All endpoints require an API key with the appropriate scope. Pass your key in the Authorization header:

Authorization: Bearer wk_your_api_key

Scopes

Comment endpoints inherit the parent entity's scope. To post a comment on a job, your key needs jobs:write. To list comments on an invoice, it needs invoices:read. The wildcard read and write scopes work as well.

How notifications fire

Posting a comment on a quote, job, invoice, or request triggers up to three internal notifications -- the same ones the dashboard fires when a user posts a comment in-app:

• comments_mention -- one per user listed in mentioned_user_ids (excluding the comment author)
• comments_reply -- to the parent comment's author when reply_to is set
• comments_new -- to the parent entity's creator

Comments on contact, event, or timesheet are stored but do not fire any internal notification (mirrors the dashboard).

The comment author never gets notified about their own comment, and a user already notified via mention won't receive a duplicate reply or new-comment notification.

The comment object

Endpoints

Post a Comment

Creates a new comment on a parent entity. Optionally @-mentions workspace members and/or replies to a previous comment.

POST /api/v1/comments

Required Scope: <module>:write of the target entity (e.g. jobs:write to post on a job)

Request Body:

curl -X POST https://app.bluesuite.com/api/v1/comments \
  -H "Authorization: Bearer wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "module_type": "job",
    "module_id": 42,
    "comment": "Heads up @sarah -- the customer wants to switch to brushed nickel.",
    "mentioned_user_ids": ["f7c19b34-5d2a-4e8f-9c6a-1234567890ab"]
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 1234,
    "workspace_id": 7,
    "related_type": "job",
    "related_id": 42,
    "comment": "Heads up @sarah -- the customer wants to switch to brushed nickel.",
    "author_id": "92775538-3a19-4651-aa28-70f782f47001",
    "reply_to": null,
    "status": "active",
    "created_at": "2024-01-15T10:30:00.000Z",
    "modified_at": null,
    "profiles": {
      "id": "92775538-3a19-4651-aa28-70f782f47001",
      "first_name": "Christian",
      "last_name": "Chung",
      "email": "christian@bluesuite.app"
    }
  }
}

The author_id is set to the user who created the API key. Make sure you create your API keys under an account that should be the recorded author.

List Comments on an Entity

Returns the comments attached to a specific parent entity, paginated newest-first. Soft-deleted comments are excluded.

GET /api/v1/comments?module_type=:module_type&module_id=:module_id

Required Scope: <module>:read of the target entity

Query Parameters:

curl "https://app.bluesuite.com/api/v1/comments?module_type=job&module_id=42" \
  -H "Authorization: Bearer wk_your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1234,
      "related_type": "job",
      "related_id": 42,
      "comment": "Heads up @sarah -- the customer wants to switch to brushed nickel.",
      "author_id": "92775538-3a19-4651-aa28-70f782f47001",
      "reply_to": null,
      "status": "active",
      "created_at": "2024-01-15T10:30:00.000Z",
      "profiles": { "first_name": "Christian", "last_name": "Chung" }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

Get a Single Comment

Returns one comment by ID.

GET /api/v1/comments/:id

Required Scope: <module>:read of the comment's parent entity

curl https://app.bluesuite.com/api/v1/comments/1234 \
  -H "Authorization: Bearer wk_your_api_key"

Response: same shape as the create response.

Delete a Comment

Soft-deletes a comment by flipping its status to trash. The row remains in the database for audit purposes but stops appearing in list responses.

DELETE /api/v1/comments/:id

Required Scope: <module>:write of the comment's parent entity

curl -X DELETE https://app.bluesuite.com/api/v1/comments/1234 \
  -H "Authorization: Bearer wk_your_api_key"

Response:

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Error Responses

{
  "success": false,
  "error": "Missing required scope: jobs:write"
}

Tips

• Use mentioned_user_ids for handing off work between team members -- the mentioned user gets the same in-app and email notification they would from a dashboard @-mention.
• reply_to keeps threaded discussions readable in the dashboard. Reply to your previous comment when you're following up rather than starting a fresh thread.
• Use list_users (or the Users endpoint) to look up workspace member UUIDs by name when building UIs that resolve mentions.
• The author of an API-posted comment is the user who created the API key. Use a dedicated bot user for integration accounts so authorship lines up with what you want shown in the dashboard.