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.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: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.true when this branch is a private 1-on-1 direct message. You cannot add additional members to a PM branch.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
Example Response
Error Codes
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.Example Request
Example Response
Additional Response Fields
Unix timestamp of the most recent message in this branch. Returns
0 if the branch has no messages.Error Codes
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
Example Request
Example Response
Error Codes
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 inmembers must already be in your friends list.
Request Body
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.Set to
true to create a private 1-on-1 direct message branch. PM branches cannot have additional members added later.Optional display name for the branch. Omit or pass
null for no name. Names are most useful for group chats.Example Request
Example Response
Error Codes
Socket.IO Events Emitted
When a branch is created, every member (including you) receives theadded_branch event:
POST /api/branch/rename
Change the display name of a branch. You must be a member of the branch. Passnull as name to clear the current name.
Request Body
Example Request
Example Response
Error Codes
Socket.IO Events Emitted
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
Example Request
Example Response
Error Codes
Socket.IO Events Emitted
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
Only the branch owner can kick members. If you need to remove yourself, use
/api/branch/leave.