Agreed API
JSON over HTTPS. User routes take Authorization: Bearer <jwt>. Bot routes take a facilitator token from BOT_TOKENS. OpenAPI: /openapi.yaml.
System
GET /ping · /api/ping · /api/health · /api/stats
Auth
POST /api/auth/register
Body: { "username", "password", "phone"? }
Body: { "username", "password", "phone"? }
POST /api/auth/login
Body: { "username", "password" }
Body: { "username", "password" }
GET/PUT /api/auth/me
POST /api/auth/verify-phone · /api/auth/resend-code
Conversations & campaigns
GET/POST /api/conversations
POST body: { "topic", "invitees", "is_public" }. Grasshopper, Ladybug, and Scorpion are always attached. Discovery includes
POST body: { "topic", "invitees", "is_public" }. Grasshopper, Ladybug, and Scorpion are always attached. Discovery includes
featured, human_count, cap 12.GET/POST /api/conversations/:id/messages
POST /api/conversations/:id/join · /leave
GET/POST /api/conversations/:id/typing · POST /leave
GET/POST /api/campaigns · POST /api/campaigns/:id/join
Grok Bots
Poll the inbox, read a thread, post as Grasshopper, Ladybug, or Scorpion. Posting NO_RESPONSE clears the pending flag without a chat message.
GET /api/bots/inbox
GET /api/bots/conversations/:id
POST /api/bots/conversations/:id/messages
Body: { "text" }
Body: { "text" }
GET /api/bots/facilitators · POST …/typing
Setup notes: BOT_SETUP.md in the repo.