Branch Messages API: Send and Manage Chat Messages

Bot is allowed — every endpoint on this page accepts bot authentication via the Authorization: <user_id> <token> header. See the Bots guide.

Branch Messages (BMessages) are the individual chat messages that live inside a Clody Branch. You can send plain text, attach up to 10 CDN-hosted files, and reply directly to previous messages. All endpoints require an authenticated, verified session cookie — unauthenticated requests return 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:

integer

Unique identifier of the message.

integer

ID of the branch this message belongs to.

integer

User ID of the member who sent the message.

string

Text body of the message. Maximum 5 000 characters.

array of strings

List of uploaded filenames attached to this message. Maximum 10 entries.

boolean

true if the message has been edited after its initial creation.

integer

Unix timestamp (seconds) when the message was created.

array of integers

List of user IDs who have marked this message as read.

object

Additional metadata. Contains a single field:

answer_to (integer | null) — the ID of the message this message is a reply to, or null if 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 (without before_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

integer

required

The ID of the branch whose messages you want to list.

integer

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.

integer

Maximum number of messages to return per page. Defaults to 30, capped at 100.

Check has_more in the response to determine whether additional pages exist. If true, call again with before_id set to the id of the oldest (first) message in the current page to load the next batch of older messages.

Example Request

curl https://your-clody-instance.com/api/bm/list \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "branch": 4, "limit": 20 }'

Example Response

{
  "messages": [
    {
      "id": 88,
      "branch": 4,
      "author": 101,
      "content": "Hey, how are you?",
      "cdn": [],
      "edited": false,
      "created_at": 1717990000,
      "read": [101, 202],
      "data": { "answer_to": null }
    },
    {
      "id": 91,
      "branch": 4,
      "author": 202,
      "content": "Doing great, thanks!",
      "cdn": [],
      "edited": false,
      "created_at": 1717990120,
      "read": [202],
      "data": { "answer_to": 88 }
    }
  ],
  "has_more": false
}

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`branch` was not provided.
`403`	`"Forbidden"`	You are not a member of this branch.

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

integer

required

The ID of the message to retrieve.

Example Request

curl https://your-clody-instance.com/api/bm/get \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 91 }'

Example Response

{
  "id": 91,
  "branch": 4,
  "author": 202,
  "content": "Doing great, thanks!",
  "cdn": [],
  "edited": false,
  "created_at": 1717990120,
  "read": [202],
  "data": { "answer_to": 88 }
}

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` was not provided.
`403`	`"Forbidden"`	You are not a member of the branch that contains this message.
`404`	`"Not Found"`	No message exists with the given ID.

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

integer

required

The ID of the branch to send the message to.

string

required

The text content of the message. Maximum 5 000 characters.

array of strings

Filenames of files to attach, as returned by /api/cdn/benches/upload. Maximum 10 items.

integer

ID of the message this message is replying to. The referenced message must exist within the same branch.

content is required and must not exceed 5 000 characters. cdn must not contain more than 10 filenames. Violating either limit returns 400 "Bad Request".

Example Request — Plain Message

curl https://your-clody-instance.com/api/bm/create \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": 4,
    "content": "Here are the updated designs!"
  }'

Example Request — Reply with Attachment

curl https://your-clody-instance.com/api/bm/create \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": 4,
    "content": "See the attached file for context.",
    "cdn": ["a1b2c3d4_mockup_v2.png"],
    "answer_to": 91
  }'

Example Response

{
  "id": 95,
  "branch": 4,
  "author": 101,
  "content": "See the attached file for context.",
  "cdn": ["a1b2c3d4_mockup_v2.png"],
  "edited": false,
  "created_at": 1718001000,
  "read": [],
  "data": { "answer_to": 91 }
}

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`branch` or `content` is missing, `cdn` has more than 10 items, or `content` exceeds 5 000 characters.
`403`	`"Forbidden"`	You are not a member of this branch.
`404`	`"Not Found"`	The `answer_to` message does not exist or belongs to a different branch.

Socket.IO Events Emitted

Event	Payload	Description
`new_bmessage`	Message object	Fired on every branch member’s socket when a new message is sent.

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

integer

required

The ID of the message to edit.

string

required

The replacement text content. Maximum 5 000 characters.

Editing a message updates its content and sets edited: true. The created_at timestamp and CDN attachments are not changed.

Example Request

curl https://your-clody-instance.com/api/bm/edit \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 95, "new_content": "See the attached file — updated link below." }'

Example Response

{
  "id": 95,
  "branch": 4,
  "author": 101,
  "content": "See the attached file — updated link below.",
  "cdn": ["a1b2c3d4_mockup_v2.png"],
  "edited": true,
  "created_at": 1718001000,
  "read": [],
  "data": { "answer_to": 91 }
}

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` or `new_content` is missing, or `new_content` exceeds 5 000 characters.
`403`	`"Forbidden"`	You are not the author of this message.
`404`	`"Not Found"`	No message exists with the given ID.

Socket.IO Events Emitted

Event	Payload	Description
`update_bmessage`	Message object	Fired on every branch member’s socket when a message is edited.

POST /api/bm/delete

Permanently delete a message you authored. Once deleted, the message cannot be recovered.

Request Body

integer

required

The ID of the message to delete.

Deletion is permanent. All branch members receive a delete_bmessage event immediately.

Example Request

curl https://your-clody-instance.com/api/bm/delete \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 95 }'

Example Response

"Success"

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` was not provided.
`403`	`"Forbidden"`	You are not the author of this message.
`404`	`"Not Found"`	No message exists with the given ID.

Socket.IO Events Emitted

Event	Payload	Description
`delete_bmessage`	`{ "id": <message_id>, "branch_id": <branch_id> }`	Fired on every branch member’s socket when a message is deleted.

POST /api/bm/mark_read

Mark a message as read by the current user. This appends your user ID to the message’s read array. If you have already marked the message as read, the call is a no-op and still returns 200.

Request Body

integer

required

The ID of the message to mark as read.

Call this endpoint whenever a message becomes visible in your UI to keep read receipts accurate. The updated message is broadcast to all branch members via update_bmessage.

Example Request

curl https://your-clody-instance.com/api/bm/mark_read \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 91 }'

Example Response

"Success"

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` was not provided.
`403`	`"Forbidden"`	You are not a member of the branch that contains this message.
`404`	`"Not Found"`	No message exists with the given ID.

Socket.IO Events Emitted

When the read status changes (i.e., you were not already in read), every branch member receives:

Event	Payload	Description
`update_bmessage`	Message object	Fired on every branch member’s socket with the updated `read` array.

Socket.IO Event Reference

Subscribe to these events on your Socket.IO client to receive real-time message updates without polling.

Event	Payload	Trigger
`new_bmessage`	Message object	A new message was sent in a branch you belong to.
`update_bmessage`	Message object	A message was edited or its `read` array changed (someone marked it as read).
`delete_bmessage`	`{ "id": integer, "branch_id": integer }`	A message was deleted from a branch you belong to.

​Message Object

​POST /api/bm/list

​Request Body

​Example Request

​Example Response

​Error Codes

​POST /api/bm/get

​Request Body

​Example Request

​Example Response

​Error Codes

​POST /api/bm/create

​Request Body

​Example Request — Plain Message

​Example Request — Reply with Attachment

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/bm/edit

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/bm/delete

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/bm/mark_read

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​Socket.IO Event Reference

Message Object

POST /api/bm/list

Request Body

Example Request

Example Response

Error Codes

POST /api/bm/get

Request Body

Example Request

Example Response

Error Codes

POST /api/bm/create

Request Body

Example Request — Plain Message

Example Request — Reply with Attachment

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/bm/edit

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/bm/delete

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/bm/mark_read

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

Socket.IO Event Reference