REST API Overview

The REST API lets your backend create, read, update, and delete collaboration data. Use it for:

• Bots — post automated comments (e.g., CI status, deployment notifications)
• Webhooks — create threads from external events
• Moderation — delete inappropriate content from your backend
• Analytics — read threads, comments, and user data
• Integrations — sync Pulse data with your own systems

Base URL

https://pulse.hire.rest/api/v1

Replace the URL

Use the Pulse server URL provided to you.

Authentication

Every request uses your secret key in the Authorization header:

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

The secret key determines which environment you're accessing. All data returned is scoped to that environment.

Secret key = backend only

Never use sk_ in frontend code. It grants full read/write access to your environment's data.

Real-Time Sync

When you create, edit, or delete data through the API, the changes appear instantly for all users connected via WebSocket. For example:

• POST a comment via API → users see it appear in the widget immediately
• DELETE a thread via API → the thread disappears from all connected browsers
• PATCH to resolve a thread → the thread shows as resolved for everyone

No extra setup needed — it works automatically.

Endpoints

Rooms

Method	Path	Description
GET	/rooms	List all rooms
GET	/rooms/:roomId	Get room with threads

Threads

Method	Path	Description
GET	/rooms/:roomId/threads	List threads in a room
POST	/rooms/:roomId/threads	Create a thread
GET	/threads/:threadId	Get thread with comments
PATCH	/threads/:threadId	Resolve or reopen
DELETE	/threads/:threadId	Delete thread

Comments

Method	Path	Description
GET	/threads/:threadId/comments	List comments
POST	/threads/:threadId/comments	Add a comment
PATCH	/comments/:commentId	Edit a comment
DELETE	/comments/:commentId	Delete a comment

Reactions

Method	Path	Description
POST	/comments/:commentId/reactions	Add reaction
DELETE	/reactions/:reactionId	Remove reaction

Users & Presence

Method	Path	Description
GET	/users	List users
GET	/rooms/:roomId/presence	Who's online

Error Format

All errors return JSON:

{ "error": "Thread not found" }

Status	Meaning
400	Bad request (missing or invalid fields)
401	Invalid or missing secret key
404	Resource not found in your environment