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
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
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
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
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
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.