REST API

API Reference

Every endpoint on your Sandra instance. All paths below are relative to your deployment URL — e.g. https://sandra.example.com or http://localhost:3000.

Chat

The core conversational interface. Sandra runs her full agent loop — memory, RAG, tools — and returns a response or a token stream.

Method	Endpoint	Description
POST	/api/chat	Send a message, receive a JSON response
POST	/api/chat/stream	Send a message, receive an SSE token stream
GET	/api/conversations/:sessionId	Retrieve full conversation history

bash

curl -X POST $SANDRA_URL/api/chat \
  -H "Content-Type: application/json" \
  -d '{ "message": "hello", "sessionId": "s1", "userId": "u1" }'

Webhooks (Channels)

Inbound webhook endpoints for messaging platforms. These are configured in each platform’s developer console to point at your Sandra deployment.

Method	Endpoint	Description
POST	/api/webhooks/whatsapp	Receives WhatsApp Business messages (via Meta webhook)
GET	/api/webhooks/whatsapp	WhatsApp webhook verification handshake
POST	/api/webhooks/instagram	Receives Instagram DMs (via Meta webhook)
GET	/api/webhooks/instagram	Instagram webhook verification handshake
POST	/api/webhooks/email	Receives inbound email (Gmail push notification or polling trigger)

Voice

Real-time voice conversation via WebSocket. The voice bridge handles STT, agent processing, and TTS in a single streaming connection.

Method	Endpoint	Description
WS	/voice	WebSocket for real-time voice — the voice-bridge service handles STT → Agent → TTS
GET	/api/voice/health	Voice bridge health check

The voice bridge is a standalone service deployed alongside Sandra. See voice-bridge/ in the repo.

Knowledge Base & Indexing

Index your own content into Sandra’s RAG pipeline. Content is chunked, embedded, and stored in pgvector for retrieval.

Method	Endpoint	Description
POST	/api/index	Index documents (text, markdown, or file upload)
POST	/api/repos	Register a GitHub/GitLab repo for automatic indexing
GET	/api/repos	List registered repositories
GET	/api/health	General health check (includes index stats)

Admin

Admin endpoints for managing tenants, tools, users, and analytics. Protected by admin-role authentication.

Method	Endpoint	Description
GET	/api/admin/tenants	List all tenants
POST	/api/admin/tenants	Create a new tenant
GET	/api/admin/analytics	Dashboard analytics (messages, users, satisfaction)
GET	/api/admin/tools	List registered tools for a tenant
POST	/api/admin/tools	Register a new dynamic tool
GET	/api/admin/api-keys	List API keys for a tenant
POST	/api/admin/api-keys	Generate a new API key

Scheduled Tasks (Crons)

These endpoints are designed to be called by a scheduler (Vercel Cron, Railway Cron, a system crontab, or any HTTP-based scheduler). They perform periodic tasks like processing reminders or polling email.

Method	Endpoint	Description
POST	/api/cron/process-reminders	Check and fire due reminders
POST	/api/cron/email-poll	Poll connected Gmail inboxes for new messages

bash

# Example: crontab entry that runs reminders every 5 minutes
*/5 * * * * curl -X POST $SANDRA_URL/api/cron/process-reminders -H "Authorization: Bearer $CRON_SECRET"

# Or add to vercel.json:
# { "crons": [{ "path": "/api/cron/process-reminders", "schedule": "*/5 * * * *" }] }

Authentication

Sandra supports two authentication modes:

API Key (external integrations)

Pass your tenant API key in the Authorization: Bearer <key> header. Generate keys from the Admin dashboard or via the admin API.

Session (web UI)

The built-in chat UI uses NextAuth session cookies. Supports Google OAuth, email magic links, or any NextAuth provider you configure.

Channels setup →