Comments

Comments belong to threads. Every thread starts with one comment.

List Comments

GET /api/v1/threads/:threadId/comments

curl https://pulse.hire.rest/api/v1/threads/thread_abc/comments \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{
  "items": [
    {
      "id": "comment_001",
      "threadId": "thread_abc",
      "userId": "user-1",
      "body": "This needs attention",
      "mentions": [],
      "createdAt": "2026-03-10T14:00:00.000Z",
      "editedAt": null
    }
  ]
}

Create Comment

POST /api/v1/threads/:threadId/comments

Adds a reply to a thread. Appears instantly in all connected browsers. Sends notifications to thread participants and mentioned users.

curl -X POST https://pulse.hire.rest/api/v1/threads/thread_abc/comments \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-2",
    "body": "On it! Will fix by EOD.",
    "mentions": ["user-1"]
  }'

Field	Type	Required	Description
userId	string	Yes	Author's user ID
body	string	Yes	Comment text
mentions	string[]	No	User IDs to @mention

Response 201:

{
  "comment": {
    "id": "comment_002",
    "threadId": "thread_abc",
    "userId": "user-2",
    "body": "On it! Will fix by EOD.",
    "mentions": ["user-1"],
    "createdAt": "2026-03-10T14:10:00.000Z",
    "editedAt": null
  }
}

Edit Comment

PATCH /api/v1/comments/:commentId

curl -X PATCH https://pulse.hire.rest/api/v1/comments/comment_002 \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Fixed! Deployed to production.",
    "mentions": []
  }'

Field	Type	Required	Description
body	string	Yes	Updated comment text
mentions	string[]	No	Updated @mentions

Response:

{
  "comment": {
    "id": "comment_002",
    "body": "Fixed! Deployed to production.",
    "editedAt": "2026-03-10T15:00:00.000Z",
    ...
  }
}

Delete Comment

DELETE /api/v1/comments/:commentId

If this was the last comment in the thread, the thread is deleted too.

curl -X DELETE https://pulse.hire.rest/api/v1/comments/comment_002 \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{ "deleted": true }