Threads

Threads are conversations, optionally pinned to a position on the page.

List Threads

GET /api/v1/rooms/:roomId/threads

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

Response:

{
  "items": [
    {
      "id": "thread_abc",
      "roomId": "dashboard",
      "resolved": false,
      "positionX": 0.45,
      "positionY": 0.72,
      "createdAt": "2026-03-10T14:00:00.000Z",
      "updatedAt": "2026-03-10T14:05:00.000Z"
    }
  ]
}

Create Thread

POST /api/v1/rooms/:roomId/threads

Creates a thread with an initial comment. The thread appears instantly in all connected browsers.

curl -X POST https://pulse.hire.rest/api/v1/rooms/dashboard/threads \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-1",
    "body": "Deployment failed — see CI logs",
    "mentions": ["user-2"],
    "position": { "x": 0.5, "y": 0.3 }
  }'

Field	Type	Required	Description
userId	string	Yes	Author's user ID (must have connected before)
body	string	Yes	First comment text
mentions	string[]	No	User IDs to @mention (sends notifications)
position	object	No	Pin position: { x, y, selector?, path? } — x/y are 0-1 range

Response 201:

{
  "thread": {
    "id": "thread_new",
    "roomId": "dashboard",
    "resolved": false,
    "position": { "x": 0.5, "y": 0.3 },
    "comments": [{
      "id": "comment_001",
      "userId": "user-1",
      "body": "Deployment failed — see CI logs",
      "mentions": ["user-2"],
      "createdAt": "2026-03-10T14:00:00.000Z"
    }],
    "createdAt": "2026-03-10T14:00:00.000Z"
  }
}

Use Case: CI Bot

Have your CI pipeline create a thread when a deployment fails. Users see it appear in the Pulse widget on the affected page.

Get Thread

GET /api/v1/threads/:threadId

Returns the thread with all its comments.

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

Response:

{
  "thread": { "id": "thread_abc", "resolved": false, ... },
  "comments": [
    { "id": "comment_001", "userId": "user-1", "body": "Original comment", ... },
    { "id": "comment_002", "userId": "user-2", "body": "Reply here", ... }
  ]
}

Resolve / Reopen

PATCH /api/v1/threads/:threadId

curl -X PATCH https://pulse.hire.rest/api/v1/threads/thread_abc \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'

Response:

{ "threadId": "thread_abc", "resolved": true }

Delete Thread

DELETE /api/v1/threads/:threadId

Deletes the thread and all its comments. Disappears from all connected browsers.

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

Response:

{ "deleted": true }