BuddyBots HTTP + WebSocket API

All JSON. When BB_TOKEN is set, send it as Authorization: Bearer <token> (the web app uses a cookie). In hosted mode (BB_MULTI=1) every route except /api/health, /api/auth/*, the OAuth/Composio callbacks and webhooks needs the bb_sid session cookie from POST /api/auth/login; ids of another organisation answer 404. Errors: { error, requestId }. Generated from server/src/routes.ts and server/src/index.ts.

WebSocket

• GET /ws — app events (WsEvent in shared/types.ts): messages, tasks, task.phase, computer.update, screen.frame (send {type:'watch',botId}), workspace.switch, chrome.ext.
• GET /ext?token=<pairing token> — the BuddyBots Chrome extension. Server → extension: {id, op:'tab.create'|'tab.get'|'tab.focus'|'tab.close'|'tab.navigate'|'tab.back'|'tab.screenshot'|'dom'|'tab.realClick'|'tab.record', tabId?, url?, fn?, args?, x?, y?, on?} (tab.realClick = a trusted click via chrome.debugger at viewport x,y; tab.record starts/stops recording the owner's own actions in that tab, relayed as {type:'event', name:'recorded', tabId, step}); extension → server: {id, ok, result|error}, {type:'hello', ua, version}, {type:'event', name:'tab.removed'|'tab.updated'|'detached', tabId}. Pairing code (http://127.0.0.1:PORT#TOKEN) from GET /api/chrome.

activity

• GET /api/activity
• GET /api/activity/export

approvals

• GET /api/approvals
• GET /api/approvals/:id
• POST /api/approvals/:id/decide

auth (hosted mode, BB_MULTI=1)

• POST /api/auth/signup — { email, password (10+), name?, orgName? } → AuthInfo, sets bb_sid cookie; creates the user, their organisation (role owner) and a first workspace.
• POST /api/auth/login — { email, password, orgId? } → AuthInfo, sets the cookie. POST /api/auth/logout clears it.
• GET /api/auth/me — AuthInfo ({ multi:false } in local mode; { multi:true } signed out).
• POST /api/auth/password — { current, next }; ends every other session of the user.
• GET /api/auth/orgs · POST /api/auth/orgs { name } (new organisation, you become owner, session switches to it) · POST /api/auth/switch { orgId }.
• GET /api/auth/members → { members, invites } · POST /api/auth/invite { email, role: 'admin'|'member' } → { token, url } (owner/admin) · POST /api/auth/accept { token } (signed in as that email) · DELETE /api/auth/members/:userId · DELETE /api/auth/invites/:id.

billing, admin, crews, shares, data (hosted mode)

• GET /api/billing → { state: LimitState, plans, breakdown, stripe, org } · POST /api/billing/checkout { plan: 'pro'|'team', seats? } → { url } · POST /api/billing/portal → { url } · POST /api/billing/budget { usd } · POST /api/billing/webhook (Stripe-signed).
• Admin (BB_ADMIN_EMAILS): GET /api/admin/orgs, POST /api/admin/orgs/:id/plan { plan, status? }, POST /api/admin/orgs/:id/credits { delta, reason }, POST /api/admin/orgs/:id/report-overage, POST /api/admin/orgs/:id/undelete, GET /api/admin/metrics, GET /api/admin/events.
• Crews: GET /api/crews, POST /api/crews/:id/apply { start? } → { bots, roomId, leadId, firstTask }.
• Built-in connectors: GET /api/connectors/builtin, POST /api/connectors/builtin/:id { fields }.
• Shares: GET /api/shares, POST /api/shares { type: 'task'|'bot'|'room', id } → { token, url }, DELETE /api/shares/:token; public page GET /s/:token.
• Trust: POST /api/auth/reset { email }, POST /api/auth/reset/finish { token, password }, POST /api/auth/verify { token }, POST /api/auth/verify/resend, POST /api/auth/accept-terms, GET /api/audit, GET /api/data/export (zip), POST /api/data/delete { confirm: <org name>, password }.
• Public: GET /api/status → { ok, version, sandbox, uptimeS, bots, multi }; site pages /, /pricing, /docs/*, /terms, /privacy, /status; app at /app.

learning

• GET /api/learning → { summary, stats, notes, paths, improvement } · POST /api/learning/notes { domain, text } · PATCH /api/learning/notes/:id { text?, enabled? } · DELETE /api/learning/notes/:id · DELETE /api/learning/paths/:id.

bootstrap

• GET /api/bootstrap — also carries auth: AuthInfo.

bots

• GET /api/bots
• POST /api/bots
• POST /api/bots/generate
• PATCH /api/bots/:id
• DELETE /api/bots/:id
• POST /api/bots/:id/duplicate
• POST /api/bots/:id/stop
• POST /api/bots/:id/read
• POST /api/bots/:id/unread
• GET /api/bots/:id/export
• POST /api/bots/import
• GET /api/bots/:id/tasks
• GET /api/bots/:id/memory
• POST /api/bots/:id/memory
• GET /api/bots/:id/analytics
• GET /api/bots/:id/computer
• POST /api/bots/:id/computer/open
• POST /api/bots/:id/computer/signin
• POST /api/bots/:id/computer/signin/done
• POST /api/bots/:id/computer/help/skip
• POST /api/bots/:id/computer/takeover
• POST /api/bots/:id/computer/show — bring the bot's tab to the front in the owner's Chrome
• POST /api/bots/:id/computer/input
• POST /api/bots/:id/computer/secret
• POST /api/bots/:id/show-me/start {context?, taskId?, stepAction?, url?, convType?, convId?} — start a demonstration: the bot pauses, (re)opens url if given, brings its tab to the front and records the owner's actions; returns {demo, computer}
• POST /api/bots/:id/show-me/stop — end it: the trace is turned into procedures (model when available) and a review card (data.tag = 'demo_review') is posted in the conversation; returns {demoId, steps, understood, message}
• POST /api/demos/:id/save {procedures?: [{title, intent?, keep?}]} / POST /api/demos/:id/discard — the owner's verdict; saved procedures appear in GET /api/learning as procedures and as lesson notes
• PATCH /api/learning/procedures/:id {title?, intent?, enabled?} · DELETE /api/learning/procedures/:id
• POST /api/bots/:id/computer/teach/start {fix?: {action, url?}} — with fix, "Show me how" for one step: the bot pauses on that page and records what the owner does; teach/stop then saves a lesson note + step path for that site (returns {lesson, domain, steps}) instead of a skill
• POST /api/bots/:id/computer/teach/start
• POST /api/bots/:id/computer/teach/stop
• POST /api/bots/:id/computer/ask

chrome

• GET /api/chrome

claude-local

• GET /api/claude-local
• POST /api/claude-local
• POST /api/claude-local/connect
• POST /api/claude-local/connect/code
• POST /api/claude-local/connect/cancel
• POST /api/claude-local/test
• POST /api/claude-local/apply

computer

• GET /api/computer/snapshots
• POST /api/computer/snapshots
• POST /api/computer/recover
• POST /api/computer/reset

connectors

• GET /api/connectors
• POST /api/connectors
• POST /api/connectors/quick
• POST /api/connectors/:id/call
• POST /api/connectors/:id/writes
• PATCH /api/connectors/:id
• DELETE /api/connectors/:id

conversations

• GET /api/conversations/:type/:id/messages
• POST /api/conversations/:type/:id/messages

ext

• GET /ext — The BuddyBots Chrome extension connects here (pairing token in the query) and relays tab + DevTools commands.

files

• GET /api/files
• GET /api/files/preview
• DELETE /api/files

health

• GET /api/health

hooks

• POST /api/hooks/:id

keys

• GET /api/keys
• PUT /api/keys/:provider
• DELETE /api/keys/:provider

login

• GET /login
• POST /login

mail

• POST /api/mail/check

memory

• PATCH /api/memory/:id
• DELETE /api/memory/:id

messages

• GET /api/messages/:id/thread
• POST /api/messages/:id/react

rooms

• GET /api/rooms
• POST /api/rooms
• PATCH /api/rooms/:id
• DELETE /api/rooms/:id
• POST /api/rooms/:id/read
• POST /api/rooms/:id/unread

routines

• GET /api/routines
• POST /api/routines
• PATCH /api/routines/:id
• DELETE /api/routines/:id
• POST /api/routines/:id/test
• GET /api/routines/:id/runs

rules

• GET /api/rules
• POST /api/rules
• DELETE /api/rules/:id

search

• GET /api/search

settings

• GET /api/settings
• PATCH /api/settings

skills

• GET /api/skills
• PUT /api/skills/:id
• DELETE /api/skills/:id

t

• GET /t/:file

tasks

• GET /api/tasks/:id
• POST /api/tasks/:id/stop

templates

• GET /api/templates
• GET /api/templates/grok-export-prompt
• POST /api/templates
• POST /api/templates/from-bot/:id
• DELETE /api/templates/:id
• GET /api/templates/:id/export
• POST /api/templates/:id/share — opt-in public link; the token is unguessable and only this template is exposed
• DELETE /api/templates/:id/share
• POST /api/templates/import — Preview only: nothing is saved until the client posts the result to /api/templates (or creates a bot from it).

upload

• POST /api/upload

usage

• GET /api/usage

workspaces

• GET /api/workspaces
• POST /api/workspaces
• POST /api/workspaces/:id/switch
• PATCH /api/workspaces/:id
• DELETE /api/workspaces/:id

ws

• GET /ws