Complete reference for Lilith's conversational AI APIs including chat, conversations, personas, and streaming.
Chat Endpoints#
Send Chat Message#
POST /v1/chat
Send a message to an AI persona and receive a response.
Request Body:
{
"conversation_id": "conv_abc123",
"persona": "zen-master",
"input": {
"text": "What is the nature of mindfulness?",
"audio": null
},
"mode": "text",
"options": {
"cite": true,
"depth": "scholarly",
"tone": "gentle",
"language": "en"
}
}
Response (Streaming SSE):
event: token
data: {"text": "Mindfulness", "index": 0}
event: token
data: {"text": " is", "index": 1}
event: citation
data: {"source": "Satipatthana Sutta", "url": "...", "span": "..."}
event: done
data: {"message_id": "msg_xyz", "total_tokens": 150}
Response (Non-streaming):
{
"message_id": "msg_xyz789",
"conversation_id": "conv_abc123",
"text": "Mindfulness is the quality of being fully present...",
"citations": [
{
"source": "Satipatthana Sutta",
"url": "https://lilith.app/sources/satipatthana",
"text_span": "awareness of the body...",
"confidence": 0.95
}
],
"audio_url": null,
"metrics": {
"latency_ms": 450,
"tokens_in": 12,
"tokens_out": 150
}
}
Chat Completion (OpenAI-compatible)#
POST /v1/chat/completion
OpenAI-compatible chat completion endpoint for drop-in replacement.
Request Body:
{
"model": "lilith-guide-v1",
"messages": [
{ "role": "system", "content": "You are a Zen meditation guide." },
{ "role": "user", "content": "Guide me through a breathing exercise." }
],
"temperature": 0.7,
"max_tokens": 500,
"stream": true
}
Conversations#
Create Conversation#
POST /v1/conversations
Request Body:
{
"persona": "stoic-mentor",
"title": "Evening reflection",
"metadata": {
"session_type": "meditation",
"tradition": "stoicism"
}
}
Response:
{
"conversation_id": "conv_new123",
"persona": "stoic-mentor",
"created_at": "2026-01-03T10:00:00Z",
"title": "Evening reflection"
}
List Conversations#
GET /v1/conversations
Query Parameters: | Parameter | Type | Description |
|-----------|------|-------------| | limit | number | Max results (default:
20, max: 100) | | offset | number | Pagination offset | | persona | string |
Filter by persona | | since | ISO8601 | Filter by date |
Response:
{
"conversations": [
{
"conversation_id": "conv_abc123",
"persona": "zen-master",
"title": "Morning meditation",
"message_count": 12,
"created_at": "2026-01-02T08:00:00Z",
"updated_at": "2026-01-02T08:30:00Z"
}
],
"total": 45,
"has_more": true
}
Get Conversation#
GET /v1/conversations/{conversationId}
Response:
{
"conversation_id": "conv_abc123",
"persona": "zen-master",
"title": "Morning meditation",
"messages": [
{
"message_id": "msg_001",
"role": "user",
"text": "Good morning. I'd like to meditate.",
"created_at": "2026-01-02T08:00:00Z"
},
{
"message_id": "msg_002",
"role": "assistant",
"text": "Good morning. Let us begin with awareness of breath...",
"citations": [...],
"created_at": "2026-01-02T08:00:05Z"
}
],
"metadata": {...}
}
Get Conversation Messages#
GET /v1/conversations/{conversationId}/messages
Paginated message retrieval for long conversations.
Query Parameters: | Parameter | Type | Description |
|-----------|------|-------------| | limit | number | Max messages
(default: 50) | | before | string | Message ID for cursor pagination | |
after | string | Message ID for cursor pagination |
Delete Conversation#
DELETE /v1/conversations/{conversationId}
Reset Conversation#
POST /v1/conversations/{conversationId}/reset
Clears conversation history while preserving metadata.
Personas#
List Personas#
GET /v1/personas
Query Parameters: | Parameter | Type | Description |
|-----------|------|-------------| | tradition | string | Filter by tradition
(zen, stoic, sufi, etc.) | | style | string | Filter by teaching style | |
language | string | Filter by supported language |
Response:
{
"personas": [
{
"persona_id": "zen-master",
"name": "Zen Master Takeshi",
"description": "A gentle guide in the Zen Buddhist tradition...",
"tradition": "zen",
"teaching_style": ["gentle", "socratic", "experiential"],
"voice_id": "zen-master-01",
"avatar_url": "https://cdn.lilith.app/avatars/zen-master.png",
"capabilities": ["meditation", "koans", "mindfulness"]
}
]
}
Get Persona Details#
GET /v1/personas/{personaId}
Response:
{
"persona_id": "zen-master",
"name": "Zen Master Takeshi",
"description": "...",
"tradition": "zen",
"lineage": "Rinzai",
"teaching_style": ["gentle", "socratic"],
"personality_traits": {
"warmth": 0.8,
"formality": 0.6,
"directness": 0.7,
"humor": 0.4
},
"voice_id": "zen-master-01",
"supported_languages": ["en", "ja"],
"topics": ["meditation", "koans", "impermanence", "mindfulness"],
"boundaries": ["no_medical_advice", "no_predictions"],
"sample_prompts": [
"What is the sound of one hand clapping?",
"Guide me through zazen meditation"
]
}
Persona Settings#
GET /v1/personas/{personaId}/settings
PATCH /v1/personas/{personaId}/settings
User-specific persona customization:
{
"tone": "challenging",
"depth": "scholarly",
"cite_mode": "dense",
"audio_enabled": true,
"preferred_voice": "zen-master-02"
}
Citations#
Get Message Citations#
GET /v1/conversations/{conversationId}/messages/{messageId}/citations
Response:
{
"citations": [
{
"citation_id": "cite_001",
"source": "Satipatthana Sutta",
"source_url": "https://lilith.app/sources/satipatthana",
"text_span": "awareness of the body in the body...",
"page": 12,
"tradition": "theravada",
"confidence": 0.95,
"license": "public_domain"
}
]
}
Verify Citation#
GET /v1/citations/{citationId}
Streaming#
SSE Streaming#
Chat responses are streamed via Server-Sent Events (SSE).
Event Types: | Event | Description | |-------|-------------| | token |
Individual text token | | citation | Citation reference | | tool_call | Tool
invocation | | tool_result | Tool response | | metrics | Response metrics |
| done | Stream complete | | error | Error occurred |
Connection:
const eventSource = new EventSource('/v1/chat?stream=true', {
headers: { Authorization: 'Bearer <token>' },
});
eventSource.addEventListener('token', (e) => {
const data = JSON.parse(e.data);
console.log(data.text);
});
WebSocket Chat#
WS /v1/chat/ws
For bidirectional real-time chat with voice support.
Message Format:
{
"type": "message",
"conversation_id": "conv_123",
"content": {
"text": "Hello",
"audio": "<base64>"
}
}
Comparative Views#
Compare Tradition Responses#
POST /v1/chat/compare
Get parallel responses from multiple personas on the same question.
Request Body:
{
"question": "What is the nature of suffering?",
"personas": ["zen-master", "stoic-mentor", "sufi-mystic"],
"options": {
"include_synthesis": true
}
}
Response:
{
"question": "What is the nature of suffering?",
"responses": [
{
"persona": "zen-master",
"text": "Suffering arises from attachment...",
"citations": [...]
},
{
"persona": "stoic-mentor",
"text": "Suffering is not in events themselves...",
"citations": [...]
},
{
"persona": "sufi-mystic",
"text": "The pain of separation from the Beloved...",
"citations": [...]
}
],
"synthesis": "While each tradition approaches suffering differently...",
"common_themes": ["attachment", "perception", "transformation"]
}
Daily Content#
Get Daily Reflection#
GET /v1/chat/daily
Query Parameters: | Parameter | Type | Description |
|-----------|------|-------------| | tradition | string | Preferred tradition
| | persona | string | Preferred persona | | date | ISO8601 | Specific date
|
Context & Memory#
Get Conversation Context#
GET /v1/conversations/{conversationId}/context
Response:
{
"summary": "User is exploring mindfulness practices...",
"topics_discussed": ["breath awareness", "walking meditation"],
"user_interests": ["beginner", "stress_relief"],
"session_count": 5
}
Update Context#
PATCH /v1/conversations/{conversationId}/context
Feedback & Ratings#
Rate Response#
POST /v1/conversations/{conversationId}/messages/{messageId}/feedback
Request Body:
{
"rating": 5,
"helpful": true,
"accurate": true,
"flags": [],
"comment": "Very insightful response"
}
Report Message#
POST /v1/conversations/{conversationId}/messages/{messageId}/report
Request Body:
{
"reason": "inaccurate_citation",
"details": "The source attribution appears incorrect"
}
Error Codes#
| Code | Description |
|---|---|
chat.rate_limited |
Request limit exceeded |
chat.model_unavailable |
AI model temporarily unavailable |
chat.guardrail_violation |
Response blocked by safety filter |
chat.context_exceeded |
Conversation context too long |
persona.not_found |
Persona ID not found |
conversation.not_found |
Conversation ID not found |
Rate Limits#
| Endpoint | Limit |
|---|---|
| Chat messages | 60 req/min |
| Conversation list | 100 req/min |
| Persona queries | 200 req/min |
| Comparative views | 10 req/min |