Branches API: Group and Direct Message Conversations

Bot authentication is accepted on read endpoints (GET /api/branches/get, GET /api/branches/overview, POST /api/branch/get) via the Authorization: <user_id> <token> header.It is rejected on all mutating endpoints (create, rename, add_member, kick, leave) — those return 400 Not Authorized when called with a bot token. Have the branch owner (a human) add the bot instead. See the Bots guide.

Branches are Clody’s fundamental unit of conversation. A branch can be a one-on-one direct message (ispm: true) or a multi-member group chat. Every branch tracks its members, owner, optional display name, and arbitrary metadata. All endpoints on this page require an authenticated, verified session cookie — unauthenticated requests return 400 "Not Authorized".

Branch Object

Every branch endpoint that returns a branch returns the following shape:

integer

Unique identifier of the branch.

array of integers

List of user IDs who currently belong to this branch.

string

Arbitrary metadata stored on the branch, serialized as a JSON string. Parse this value with JSON.parse() (or your language’s equivalent) before accessing its contents.

boolean

true when this branch is a private 1-on-1 direct message. You cannot add additional members to a PM branch.

integer

User ID of the branch owner. Only the owner can kick members.

string | null

Display name of the branch, or null if none has been set.

GET /api/branches/get

Retrieve the list of branch IDs that the currently authenticated user belongs to. Use this as a lightweight membership check before fetching full branch details. No request body required.

This endpoint uses GET — do not send a request body.

Example Request

curl https://your-clody-instance.com/api/branches/get \
  --cookie "session=<your_session_cookie>"

Example Response

[1, 4, 17, 42]

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.

GET /api/branches/overview

Fetch a summary of every branch the current user belongs to, enriched with unread message count and last activity timestamp. Ideal for building sidebar or inbox list views without fetching each branch individually. No request body required.

Use unread to display notification badges and last_at to sort branches by most recent activity.

Example Request

curl https://your-clody-instance.com/api/branches/overview \
  --cookie "session=<your_session_cookie>"

Example Response

[
  {
    "id": 4,
    "members": [101, 202],
    "data": "",
    "ispm": true,
    "owner": 101,
    "name": null,
    "unread": 3,
    "last_at": 1718000000
  },
  {
    "id": 17,
    "members": [101, 202, 303],
    "data": "",
    "ispm": false,
    "owner": 101,
    "name": "Team Chat",
    "unread": 0,
    "last_at": 1717995600
  }
]

Additional Response Fields

integer

Number of messages in this branch that you have not yet read (authored by other members).

integer

Unix timestamp of the most recent message in this branch. Returns 0 if the branch has no messages.

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.

POST /api/branch/get

Fetch the full branch object for a single branch by its ID. You must be a member of the branch to retrieve it.

Request Body

integer

required

The ID of the branch to retrieve.

Example Request

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

Example Response

{
  "id": 4,
  "members": [101, 202],
  "data": "",
  "ispm": true,
  "owner": 101,
  "name": null
}

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 this branch.
`404`	`"Not Found"`	No branch exists with the given ID.

POST /api/branch/create

Create a new branch. You are automatically set as the owner and added as the first member. All users you pass in members must already be in your friends list.

Request Body

array of integers

required

User IDs to add to the branch alongside yourself. Every user in this list must be your friend. Pass an empty array ([]) to create a branch with only yourself.

boolean

required

Set to true to create a private 1-on-1 direct message branch. PM branches cannot have additional members added later.

string

Optional display name for the branch. Omit or pass null for no name. Names are most useful for group chats.

When ispm is true, the branch is locked to exactly the members specified at creation time — you cannot call /api/branch/add_member on it afterward.

Example Request

curl https://your-clody-instance.com/api/branch/create \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [202, 303],
    "ispm": false,
    "name": "Design Squad"
  }'

Example Response

{
  "id": 53,
  "members": [101, 202, 303],
  "data": "",
  "ispm": false,
  "owner": 101,
  "name": "Design Squad"
}

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`members` or `ispm` was not provided.
`403`	`"Anybody isn't friend"`	At least one user in `members` is not in your friends list.
`404`	`"<id> hasn't found"`	A user ID in `members` does not exist.

Socket.IO Events Emitted

When a branch is created, every member (including you) receives the added_branch event:

Event	Payload	Description
`added_branch`	Branch object	Fired on each member’s socket connection when they are added to a branch.

POST /api/branch/rename

Change the display name of a branch. You must be a member of the branch. Pass null as name to clear the current name.

Request Body

integer

required

The ID of the branch to rename.

string | null

required

The new display name, or null to remove the existing name.

Example Request

curl https://your-clody-instance.com/api/branch/rename \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 53, "name": "Frontend Team" }'

Example Response

{
  "id": 53,
  "members": [101, 202, 303],
  "data": "",
  "ispm": false,
  "owner": 101,
  "name": "Frontend Team"
}

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 this branch.
`404`	`"Not Found"`	No branch exists with the given ID.

Socket.IO Events Emitted

Event	Payload	Description
`update_branch`	`{ "branch_id": <int> }`	Fired on every member’s socket when the branch is renamed.

POST /api/branch/add_member

Add a new member to an existing group branch. You must be a current member of the branch, the user you are adding must be your friend, and the branch must not be a PM (ispm: false).

Request Body

integer

required

The ID of the branch to add the member to.

integer

required

The user ID of the person to add.

You cannot add members to a PM branch (ispm: true). Attempting to do so returns 403 "This is PM".

Example Request

curl https://your-clody-instance.com/api/branch/add_member \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 53, "member": 404 }'

Example Response

"Success"

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` or `member` was not provided.
`403`	`"Forbidden"`	You are not a member of this branch.
`403`	`"This isn't your friend"`	The target user is not in your friends list.
`403`	`"This is PM"`	The branch is a PM; members cannot be added.
`404`	`"Not Found"`	The branch or the target user does not exist.

Socket.IO Events Emitted

Event	Payload	Description
`added_branch`	Branch object	Fired on the newly added member’s socket.

POST /api/branch/kick

Remove a member from a branch. You must be the branch owner. You cannot kick yourself (use /api/branch/leave instead).

Request Body

integer

required

The ID of the branch.

integer

required

The user ID of the member to remove.

Only the branch owner can kick members. If you need to remove yourself, use /api/branch/leave.

Example Request

curl https://your-clody-instance.com/api/branch/kick \
  --cookie "session=<your_session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 53, "member": 303 }'

Example Response

"Success"

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` or `member` was not provided.
`400`	`"Can't kick the owner"`	You attempted to kick yourself (the owner).
`403`	`"Forbidden"`	You are not the branch owner.
`404`	`"Not Found"`	The branch or the target user does not exist.
`404`	`"That is not a member"`	The target user exists but is not a member of this branch.

Socket.IO Events Emitted

Event	Payload	Description
`kicked_from_branch`	`{ "id": <branch_id>, "name": <branch_name> }`	Fired on the kicked member’s socket.

POST /api/branch/leave

Leave a branch voluntarily. The branch owner cannot leave — you must transfer ownership or delete the branch first.

Request Body

integer

required

The ID of the branch to leave.

If you are the branch owner, you cannot leave. The server returns 400 "You are owner". Ownership transfer is required before leaving.

Example Request

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

Example Response

"Success"

Error Codes

Status	Message	Description
`400`	`"Not Authorized"`	Missing or invalid session cookie.
`400`	`"Bad Request"`	`id` was not provided.
`400`	`"You are owner"`	You are the branch owner and cannot leave.
`404`	`"Not Found"`	No branch exists with the given ID.

Socket.IO Events Emitted

Event	Payload	Description
`left_branch`	`{ "id": <branch_id>, "member": <display_name> }`	Fired on every remaining member’s socket when someone leaves.

Socket.IO Event Reference

The following real-time events relate to branch membership and metadata changes. Subscribe to these on your Socket.IO client to keep your UI in sync without polling.

Event	Payload	Trigger
`added_branch`	Branch object	You were added to a branch (on creation or via `add_member`).
`update_branch`	`{ "branch_id": integer }`	A branch you belong to was renamed. Re-fetch the branch to get the updated name.
`kicked_from_branch`	`{ "id": integer, "name": string \| null }`	You were removed from a branch by the owner.
`left_branch`	`{ "id": integer, "member": string }`	A member left a branch you belong to. `member` is their display name.

​Branch Object

​GET /api/branches/get

​Example Request

​Example Response

​Error Codes

​GET /api/branches/overview

​Example Request

​Example Response

​Additional Response Fields

​Error Codes

​POST /api/branch/get

​Request Body

​Example Request

​Example Response

​Error Codes

​POST /api/branch/create

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/branch/rename

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/branch/add_member

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/branch/kick

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​POST /api/branch/leave

​Request Body

​Example Request

​Example Response

​Error Codes

​Socket.IO Events Emitted

​Socket.IO Event Reference

Branch Object

GET /api/branches/get

Example Request

Example Response

Error Codes

GET /api/branches/overview

Example Request

Example Response

Additional Response Fields

Error Codes

POST /api/branch/get

Request Body

Example Request

Example Response

Error Codes

POST /api/branch/create

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/branch/rename

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/branch/add_member

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/branch/kick

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

POST /api/branch/leave

Request Body

Example Request

Example Response

Error Codes

Socket.IO Events Emitted

Socket.IO Event Reference