User record (isbot = true) and a long-lived API token. Use the token in the Authorization header to call the rest of the Clody API as the bot.
For a conceptual overview and usage examples, see the Bots guide.
Authentication
All/api/bot/* and /api/bots/* endpoints require a human session cookie — you cannot manage bots using another bot’s token.
Other endpoints across the API accept bot authentication via a header instead of a session cookie:
<user_id> is the bot’s user field (the backing user ID) and <token> is the plaintext token returned by /api/bot/create or /api/bot/regenerate.
Send
user, not id. id is the internal bot record ID; user is the user ID the rest of the API expects.POST /api/bot/create
Create a new bot owned by the current session user.Request body
string
required
Username for the bot. Trimmed. Max 32 characters. Must contain the substring
bot (case-insensitive). Must be unique across all users.Response 200
Errors
POST /api/bot/edit
Update the bot’s display name and description.Request body
number
required
Bot record ID (the
id field from create/list responses).string
required
New display name. Trimmed. Max 64 characters after trimming; must be non-empty.
string
Optional. Trimmed and truncated to 300 characters. Pass
"" to clear.Response 200
Returns the updated bot summary (without token).
Errors
POST /api/bot/regenerate
Issue a new token and invalidate the old one immediately.Request body
number
required
Bot record ID.
Response 200
Errors
POST /api/bot/delete
Permanently delete the bot. This also deletes the bot’s backing user account and removes it from every Branch it was a member of. Messages the bot sent are not deleted.Request body
number
required
Bot record ID.
Response 200
Errors
GET /api/bots/get
List every bot owned by the current session user. Sorted by botid descending (newest first).
Response 200
token field is not included — it is only visible at creation and regeneration time.
Errors
POST /api/bot/get
Get a single bot you own.Request body
number
required
Bot record ID.
Response 200
Returns the bot summary. Note that the token field here contains the hash of the token, not the plaintext — useful only for identifying whether the token has changed, not for authenticating.
Errors
Bot Panel
GET /bots_panel — renders the built-in web UI for managing bots. Requires a human session (redirects to /app/login otherwise). This is a page, not a JSON endpoint.