API Reference
HTTP Endpoints
REST API routes exposed by the Aelio server.
Public endpoints (no auth)
| Method | Path | Purpose |
|---|---|---|
GET | /health | Liveness probe |
GET | /ready | Readiness (db, migrations, widget, sdk status) |
GET | /widget.js | Serve widget IIFE bundle |
GET | /demo.html | Static demo page |
GET | /telemetry | Telemetry dashboard HTML |
Protected endpoints (Bearer AELIO_SDK_SECRET)
| Method | Path | Purpose |
|---|---|---|
POST | /auth/magic-link | Issue magic link for widget auth |
GET | /auth/verify | Verify magic link → session token |
POST | /proactive | Send proactive message |
POST | /proactive/opt-in | Set customer proactive opt-in |
GET | /api/v1/telemetry/events | Sunjet conversation events |
GET | /api/v1/telemetry/turn-calls | Per-turn LLM call records |
Also accepts x-aelio-secret header.
WhatsApp webhooks
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /wa/webhook | Meta verify token | Subscription challenge |
POST | /wa/webhook | HMAC signature | Inbound WhatsApp messages |
Test endpoints (AELIO_TEST_MODE=1)
| Method | Path | Purpose |
|---|---|---|
GET | /__test__/whatsapp/outbox | Mock WhatsApp sent messages |
GET | /__test__/sdk/functions | Registered SDK function names |
GET | /diagnostics | Memory, paths, SDK catalog |
Endpoint details
GET /health
{
"status": "ok",
"version": "0.1.0"
}GET /ready
{
"status": "ready",
"checks": {
"database": "ok",
"migrations": "ok",
"widget": "ok",
"sdk": { "connected": true, "functions": 11 }
}
}POST /auth/magic-link
Request:
{
"email": "user@example.com",
"externalId": "user_abc123"
}Response:
{
"url": "https://your-server/auth/verify?token=..."
}GET /auth/verify?token=...
Response:
{
"customerId": "user_abc123",
"externalId": "user_abc123",
"email": "user@example.com",
"sessionToken": "eyJ..."
}POST /proactive
Request:
{
"customerExternalId": "user_abc123",
"channel": "web",
"content": "Your order shipped!",
"dedupKey": "ship-A123"
}Response (success):
{ "accepted": true, "messageId": "msg_..." }Response (blocked):
{ "accepted": false, "reason": "Customer has not opted in" }POST /proactive/opt-in
Request:
{
"customerExternalId": "user_abc123",
"optIn": true
}