Getting Started

Quickstart

Send your first message to Sandra in under 5 minutes. No SDK required — just HTTP.

Throughout these docs, replace SANDRA_URL with wherever your Sandra instance is deployed — e.g. https://sandra.example.com or http://localhost:3000 for local development.

1. Send a message (JSON)

The simplest integration: a single POST to /api/chat. Sandra runs her full agent loop — RAG retrieval, tools, memory — and returns a response.

bash

curl -X POST $SANDRA_URL/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What services does your platform offer?",
    "sessionId": "my-session-001",
    "userId": "user-abc",
    "language": "en"
  }'

json

{
  "response": "Based on the knowledge base, the platform offers...",
  "sessionId": "my-session-001",
  "toolsUsed": ["searchKnowledgeBase"],
  "language": "en"
}

Field	Required	Description
message	✅	The user’s message text
sessionId	Recommended	Reuse across turns — Sandra keeps conversation history per session
userId	Recommended	Stable user ID — Sandra builds long-term memory per user across sessions
language	Optional	en · fr · ht (Haitian Creole). Falls back to user preference or auto-detect
channel	Optional	web · whatsapp · instagram · email · voice. Controls response formatting
tenantId	Optional	For multi-tenant deployments — routes to the correct tenant context

2. Stream the response (SSE)

For chat UIs, use the streaming endpoint. Sandra emits tokens as they are generated.

javascript

const res = await fetch(`${SANDRA_URL}/api/chat/stream`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Search the web for the latest news about AI in education',
    sessionId: 'my-session-001',
    userId: 'user-abc',
    language: 'en',
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  for (const line of decoder.decode(value).split('\n')) {
    if (!line.startsWith('data: ')) continue;
    const event = JSON.parse(line.slice(6));

    if (event.type === 'token')     appendToUI(event.token);
    if (event.type === 'tool_call') showToolIndicator(event.tool);
    if (event.type === 'done')      finalizeMessage(event.response);
    if (event.type === 'error')     handleError(event.message);
  }
}

Event type	Payload	Description
start	{ sessionId }	Stream has begun
token	{ token }	Incremental response text — append to your UI
tool_call	{ tool, input, result }	Sandra invoked a tool; show a “searching…” indicator
done	{ response, sessionId, toolsUsed }	Final complete response; stream is finished
error	{ message }	An error occurred

3. Maintain conversation history

Pass the same sessionId on every turn. Sandra automatically loads recent messages as context. Retrieve the full history at any time:

bash

GET $SANDRA_URL/api/conversations/my-session-001

4. Set the language

Sandra responds natively in English, French, and Haitian Creole. Pass the language per request, or let Sandra remember it per user across sessions.

json

{ "language": "ht" }   // Haitian Creole
{ "language": "fr" }   // French
{ "language": "en" }   // English (default)

If you pass a userId and the user has a saved language preference, Sandra will use that preference as a fallback — even if you don't send a language field.

Self-hosting Sandra

Sandra is a standard Next.js app backed by PostgreSQL (with pgvector). To run your own instance:

Clone the repo and install dependencies
Set up a PostgreSQL database with the pgvector extension
Copy .env.example to .env and fill in your API keys (Gemini, OpenAI, etc.)
Run npx prisma migrate deploy to create the schema
Run npx prisma db seed to seed your first tenant
Start with npm run dev or deploy to Vercel / any Node.js host

Sandra works on Vercel, Railway, Fly.io, a bare VM, or any platform that runs Node.js 20+.

API Reference →

Full endpoint reference with all parameters.

Channels →

Connect WhatsApp, Instagram, email, or voice.