Authentication
All API requests require an API key passed in thex-api-key header:
hp_.
Sending Messages
Informational Messages
Send status updates, logs, reports, or any content that doesn’t require a response. Messages support full markdown.info (blue), success (green), warning (yellow), error (red)
Messages with Reviews
Send a message that requires human interaction:Streaming Replies
For agents that produce a reply token-by-token, Placet supports a draft-then-update model:- Start the draft —
POST /api/v1/messageswithstreamId(a stable id for this turn),streamState: "streaming", and the partialtextso far. The response contains the persisted message id. - Append updates —
PATCH /api/v1/messages/streams/:streamIdwith the latest accumulatedtextwhenever new tokens arrive. Throttle these to a few per second; the WebSocketmessage:deltaevent drives instant UI updates between PATCH calls. - Finalise —
PATCH /api/v1/messages/streams/:streamIdwith the finaltextandcomplete: true. The frontend stops treating the row as a live draft and pins it back into chronological order.
(channelId, streamId) pair is unique, so the first POST is idempotent: a retried POST returns the existing draft rather than creating a duplicate row. Refreshing the chat mid-stream redisplays whatever has been PATCHed so far — the streamed reply never disappears on reload.
