Bot is allowed — every endpoint on this page accepts bot authentication via the
Authorization: <user_id> <token> header. See the Bots guide.400 "Not Authorized". You must be a member of the branch to interact with its messages.
Attachment uploads: Before referencing files in the
cdn field, upload them via POST /api/cdn/benches/upload. Use the returned filenames when creating or referencing messages.Message Object
Every message endpoint returns messages in the following shape:Additional metadata. Contains a single field:
answer_to(integer | null) — the ID of the message this message is a reply to, ornullif it is not a reply.
POST /api/bm/list
Retrieve a paginated list of messages for a given branch. Each page is returned in oldest-to-newest order. The first call (withoutbefore_id) returns the most recent messages in the branch. To page further back in history, pass before_id — the server returns only messages whose id is strictly less than that value, so each call walks backward toward older content.
Request Body
Pagination cursor. The response will only include messages with an
id strictly less than this value (i.e., messages older than the one with this ID). Omit on the first request to fetch the most recent messages.Example Request
Example Response
Error Codes
POST /api/bm/get
Fetch a single message by its ID. You must be a member of the branch that contains the message.Request Body
Example Request
Example Response
Error Codes
POST /api/bm/create
Send a new message to a branch. You must be a member of the branch. Optionally attach files or reply to a previous message.Request Body
Filenames of files to attach, as returned by
/api/cdn/benches/upload. Maximum 10 items.ID of the message this message is replying to. The referenced message must exist within the same branch.
Example Request — Plain Message
Example Request — Reply with Attachment
Example Response
Error Codes
Socket.IO Events Emitted
POST /api/bm/edit
Edit the text content of a message you authored. Only the original author can edit a message. On success,edited is set to true in the returned object.
Request Body
Editing a message updates its
content and sets edited: true. The created_at timestamp and CDN attachments are not changed.Example Request
Example Response
Error Codes
Socket.IO Events Emitted
POST /api/bm/delete
Permanently delete a message you authored. Once deleted, the message cannot be recovered.Request Body
Example Request
Example Response
Error Codes
Socket.IO Events Emitted
POST /api/bm/mark_read
Mark a message as read by the current user. This appends your user ID to the message’sread array. If you have already marked the message as read, the call is a no-op and still returns 200.
Request Body
Example Request
Example Response
Error Codes
Socket.IO Events Emitted
When the read status changes (i.e., you were not already inread), every branch member receives: