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

P2P State

Method	Path	Description
GET	/rooms/:roomId/p2p/state	Fetch persisted CRDT state
PUT	/rooms/:roomId/p2p/state	Upsert CRDT snapshot
DELETE	/rooms/:roomId/p2p/state	Clear P2P state for a room

TURN Credentials

Method	Path	Description
GET	/turn-credentials	Mint time-limited TURN credentials

Auth for P2P endpoints

GET and PUT on P2P state accept either sk_ (secret key) or JWT token auth. DELETE requires sk_ only. TURN credentials accept either.

Rate Limiting

All API endpoints are rate-limited to 100 requests per minute per IP address. Exceeding this limit returns a 429 Too Many Requests response.

Endpoint	Limit
All API routes	100/min
POST /admin/auth/login	5/min

Error Format

All errors return JSON:

{ "error": "Thread not found" }

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key/token
403	Forbidden — file type not allowed
404	Not found
409	Conflict — duplicate slug or identifier
413	Payload too large — file exceeds size limit
429	Too many requests — rate limit exceeded
500	Internal server error