REST, WebSocket, and gRPC API for the Psyche AI Virtual Assistant Platform
The Psyche platform exposes three API interfaces for creating and managing AI-powered virtual assistants in video conferences.
| Interface | Protocol | Use Case | Latency |
|---|---|---|---|
| REST API | HTTP/JSON | CRUD operations, client API | <50ms |
| WebSocket | WS/JSON | Real-time events, streaming | <20ms |
| gRPC | HTTP/2 | Service-to-service, audio/video | <10ms |
Base URL: http://localhost:8000 (development) API Version: v1
Prefix: /api/v1
Table of Contents#
- Authentication
- Sessions API
- Personas API
- Knowledge Base API
- Tools API
- Webhooks API
- WebSocket API
- Health and Status
- Error Handling
- Rate Limiting
Authentication#
All API requests require authentication via JWT tokens or API keys.
JWT Authentication#
POST /api/v1/auth/token
Content-Type: application/json
Request:
{
"email": "user@example.com",
"password": "secure_password"
}
Response: 200 OK
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
Use the access token in subsequent requests:
Authorization: Bearer <access_token>
API Key Authentication#
X-API-Key: sk_live_xxxxxxxxxxxxx
API keys are managed via the Admin Dashboard (apps/psyche/admin).
Sessions API#
Manage AI virtual assistant sessions in video conferences.
Create Session#
POST /api/v1/sessions
Content-Type: application/json
Authorization: Bearer <token>
Request:
{
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"meeting_url": "https://zoom.us/j/1234567890",
"platform": "zoom",
"config": {
"auto_join": true,
"record": false,
"computer_use_enabled": false
},
"metadata": {
"customer_id": "cust_123",
"department": "sales"
}
}
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
persona_id |
UUID | Yes | ID of the AI persona to use |
meeting_url |
string | No | Video conference URL |
platform |
enum | No | Platform: zoom, teams, meet, webex |
config.auto_join |
bool | No | Auto-join meeting (default: false) |
config.record |
bool | No | Record session (default: false) |
config.computer_use_enabled |
bool | No | Enable computer use (default: false) |
metadata |
object | No | Custom metadata key-value pairs |
Response: 201 Created
{
"data": {
"id": "660e8400-e29b-41d4-a716-446655440001",
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"meeting_url": "https://zoom.us/j/1234567890",
"platform": "zoom",
"config": {
"auto_join": true,
"record": false,
"computer_use_enabled": false
},
"metadata": {
"customer_id": "cust_123",
"department": "sales"
},
"created_at": "2026-01-31T10:00:00Z",
"updated_at": "2026-01-31T10:00:00Z"
}
}
List Sessions#
GET /api/v1/sessions?page=1&per_page=20&status=active
Authorization: Bearer <token>
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
int | 1 | Page number (1-indexed) |
per_page |
int | 20 | Items per page (1-100) |
status |
enum | -- | Filter by status |
persona_id |
UUID | -- | Filter by persona |
platform |
enum | -- | Filter by platform |
Response: 200 OK
{
"data": [
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "active",
"platform": "zoom",
"created_at": "2026-01-31T10:00:00Z"
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 42,
"total_pages": 3
}
}
Get Session#
GET /api/v1/sessions/{session_id}
Authorization: Bearer <token>
Response: 200 OK
{
"data": {
"id": "660e8400-e29b-41d4-a716-446655440001",
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "active",
"meeting_url": "https://zoom.us/j/1234567890",
"platform": "zoom",
"config": {
"auto_join": true,
"record": false,
"computer_use_enabled": false
},
"metadata": { "customer_id": "cust_123", "department": "sales" },
"started_at": "2026-01-31T10:05:00Z",
"created_at": "2026-01-31T10:00:00Z",
"updated_at": "2026-01-31T10:05:00Z",
"stats": {
"duration_seconds": 300,
"turns": 15,
"tools_used": 2
}
}
}
Session Actions#
POST /api/v1/sessions/{session_id}/start
POST /api/v1/sessions/{session_id}/join-meeting
POST /api/v1/sessions/{session_id}/pause
POST /api/v1/sessions/{session_id}/resume
POST /api/v1/sessions/{session_id}/end
DELETE /api/v1/sessions/{session_id}
Join Meeting Request:
{
"meeting_url": "https://zoom.us/j/1234567890",
"meeting_password": "optional_password"
}
Session Status Lifecycle:
| Status | Description |
|---|---|
pending |
Session created, awaiting start |
connecting |
Connecting to video conference |
active |
Session active, AI participating |
paused |
Session temporarily paused |
ended |
Session completed |
error |
Session encountered an error |
Get Session Metrics#
GET /api/v1/sessions/metrics
Authorization: Bearer <token>
Response: 200 OK
{
"data": {
"total_sessions": 1542,
"active_sessions": 12,
"average_duration_seconds": 845,
"sessions_by_status": {
"pending": 5,
"active": 12,
"ended": 1520,
"error": 5
},
"sessions_by_platform": {
"zoom": 850,
"teams": 420,
"meet": 250,
"webex": 22
}
}
}
Personas API#
Manage AI persona configurations including personality, voice, and avatar.
Create Persona#
POST /api/v1/personas
Content-Type: application/json
Authorization: Bearer <token>
Request:
{
"name": "sales-assistant",
"display_name": "Sarah - Sales Assistant",
"description": "Professional sales assistant with product expertise",
"system_prompt": "You are Sarah, a knowledgeable sales assistant...",
"personality": {
"formality": 0.7,
"friendliness": 0.8,
"verbosity": 0.5,
"humor": 0.3,
"empathy": 0.9,
"assertiveness": 0.6
},
"voice": {
"voice_id": "elevenlabs_sarah",
"provider": "elevenlabs",
"speed": 1.0,
"pitch": 1.0,
"custom_voice_enabled": false
},
"avatar": {
"model_id": "3dgs_professional_female_001",
"style": "professional",
"background": "office",
"camera_position": "front"
},
"expertise": ["sales", "product-knowledge", "customer-service"],
"tools": ["crm-lookup", "product-catalog", "calendar-booking"]
}
Personality Traits (0.0 - 1.0):
| Trait | Low Value | High Value |
|---|---|---|
formality |
Casual, relaxed | Professional, formal |
friendliness |
Reserved | Warm, approachable |
verbosity |
Concise | Detailed, thorough |
humor |
Serious | Light-hearted |
empathy |
Task-focused | Emotionally attuned |
assertiveness |
Accommodating | Direct, confident |
Voice Providers:
| Provider | Features |
|---|---|
elevenlabs |
Premium quality, voice cloning |
xtts |
Local model, 19 languages |
cartesia |
Low latency (<50ms) |
openai |
Good quality, wide language |
Response: 201 Created
List Personas#
GET /api/v1/personas?page=1&per_page=20&search=sales
Authorization: Bearer <token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
search |
string | Search by name/description |
is_active |
bool | Filter by active status |
expertise |
string | Filter by expertise tag |
Update Persona#
PATCH /api/v1/personas/{persona_id}
Content-Type: application/json
Authorization: Bearer <token>
Supports partial updates:
{
"personality": {
"friendliness": 0.9
},
"voice": {
"speed": 1.1
}
}
Persona Actions#
GET /api/v1/personas/{persona_id}
POST /api/v1/personas/{persona_id}/activate
POST /api/v1/personas/{persona_id}/deactivate
POST /api/v1/personas/{persona_id}/clone
DELETE /api/v1/personas/{persona_id}
Knowledge Base API#
Manage documents and perform semantic search for RAG.
Upload Document#
POST /api/v1/knowledge/documents/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>
Form Data:
| Field | Type | Required | Description |
|---|---|---|---|
file |
file | Yes | Document file |
persona_id |
UUID | No | Associate with persona |
tags |
array | No | Tags for filtering |
metadata |
object | No | Custom metadata |
Supported File Types:
| Type | Extensions | Max Size |
|---|---|---|
.pdf |
50 MB | |
| Word | .docx, .doc |
25 MB |
| HTML | .html, .htm |
10 MB |
| Markdown | .md |
5 MB |
| CSV | .csv |
25 MB |
| JSON | .json |
10 MB |
| Plain Text | .txt |
5 MB |
Response: 201 Created
{
"data": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"title": "Product Catalog 2026",
"source_type": "pdf",
"status": "processing",
"chunk_count": 0,
"file_size_bytes": 2456789,
"created_at": "2026-01-31T10:00:00Z"
}
}
Document Processing Status:
| Status | Description |
|---|---|
pending |
Awaiting processing |
processing |
Being chunked and embedded |
ready |
Available for search |
error |
Processing failed |
Semantic Search#
POST /api/v1/knowledge/search
Content-Type: application/json
Authorization: Bearer <token>
Request:
{
"query": "What are the pricing options for enterprise customers?",
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"tags": ["pricing", "enterprise"],
"top_k": 10,
"score_threshold": 0.7
}
Parameters:
| Field | Type | Default | Description |
|---|---|---|---|
query |
string | -- | Search query (required) |
persona_id |
UUID | -- | Filter by persona |
tags |
array | -- | Filter by tags |
top_k |
int | 10 | Max results (1-100) |
score_threshold |
float | 0.5 | Min similarity score (0-1) |
Response: 200 OK
{
"data": {
"results": [
{
"document_id": "770e8400-e29b-41d4-a716-446655440002",
"document_title": "Product Catalog 2026",
"chunk_index": 42,
"content": "Enterprise pricing starts at $10,000/month...",
"score": 0.92,
"metadata": {
"section": "Pricing",
"page": 15
}
}
],
"query": "What are the pricing options for enterprise customers?",
"total_results": 5,
"processing_time_ms": 45
}
}
Document Management#
GET /api/v1/knowledge/documents # List documents
GET /api/v1/knowledge/documents/{document_id} # Get document details
DELETE /api/v1/knowledge/documents/{document_id} # Delete document
POST /api/v1/knowledge/documents/{document_id}/reprocess # Re-process document
Tools API#
Register and manage tools that AI personas can invoke during sessions.
Register Tool#
POST /api/v1/tools
Content-Type: application/json
Authorization: Bearer <token>
Request:
{
"name": "calendar-booking",
"display_name": "Calendar Booking",
"description": "Book meetings on the calendar",
"type": "api",
"config": {
"endpoint": "https://api.calendar.example.com/v1/bookings",
"method": "POST",
"auth_type": "oauth2",
"auth_config": {
"client_id": "calendar_client_123"
}
},
"parameters": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Meeting title"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Meeting start time (ISO 8601)"
},
"duration_minutes": {
"type": "integer",
"description": "Meeting duration in minutes"
},
"attendees": {
"type": "array",
"items": { "type": "string", "format": "email" },
"description": "List of attendee emails"
}
},
"required": ["title", "start_time", "duration_minutes"]
}
}
Tool Types:
| Type | Description |
|---|---|
function |
Local function execution |
api |
External API call |
mcp |
Model Context Protocol server |
webhook |
Webhook trigger |
Authentication Types:
| Type | Description |
|---|---|
none |
No authentication |
api_key |
API key in header |
basic |
HTTP Basic authentication |
bearer |
Bearer token |
oauth2 |
OAuth 2.0 flow |
Tool Management#
GET /api/v1/tools # List tools
GET /api/v1/tools/{tool_id} # Get tool details
GET /api/v1/tools/{tool_id}/schema # Get tool JSON schema
PATCH /api/v1/tools/{tool_id} # Update tool
DELETE /api/v1/tools/{tool_id} # Delete tool
POST /api/v1/tools/{tool_id}/test # Test tool execution
POST /api/v1/tools/{tool_id}/activate # Activate tool
POST /api/v1/tools/{tool_id}/deactivate # Deactivate tool
Test Tool Request:
{
"parameters": {
"title": "Demo Meeting",
"start_time": "2026-02-01T14:00:00Z",
"duration_minutes": 30
}
}
Webhooks API#
Configure webhooks for event notifications.
Create Webhook#
POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer <token>
Request:
{
"name": "session-events-webhook",
"url": "https://api.example.com/webhooks/psyche",
"events": ["session.started", "session.ended", "conversation.message"],
"secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx",
"headers": {
"X-Custom-Header": "custom-value"
}
}
Available Webhook Events#
| Event | Description |
|---|---|
session.started |
Session became active |
session.ended |
Session completed |
session.paused |
Session paused |
session.resumed |
Session resumed |
session.error |
Session encountered error |
conversation.started |
Conversation began |
conversation.turn |
Conversation turn completed |
conversation.message |
New message in conversation |
meeting.joined |
Joined video conference |
meeting.left |
Left video conference |
tool.executed |
Tool was executed |
tool.error |
Tool execution failed |
emotion.detected |
User emotion detected |
error.occurred |
General error occurred |
Webhook Payload Format#
{
"id": "evt_xxxxxxxxxxxxxxxx",
"type": "session.started",
"created_at": "2026-01-31T10:05:00Z",
"data": {
"session_id": "660e8400-e29b-41d4-a716-446655440001",
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"platform": "zoom"
}
}
Signature Verification:
Webhook payloads include X-Webhook-Signature: sha256=xxxxx. Verify using
HMAC-SHA256 with your webhook secret.
Webhook Management#
GET /api/v1/webhooks # List webhooks
GET /api/v1/webhooks/{webhook_id} # Get webhook details
PATCH /api/v1/webhooks/{webhook_id} # Update webhook
DELETE /api/v1/webhooks/{webhook_id} # Delete webhook
POST /api/v1/webhooks/{webhook_id}/test # Send test event
GET /api/v1/webhooks/{webhook_id}/deliveries # View delivery history
WebSocket API#
Real-time bidirectional communication for session events and control.
Connection#
wss://localhost:8000/api/v1/ws
wss://localhost:8000/api/v1/ws/sessions/{session_id}
Authentication (choose one):
// Option 1: Query parameter
const ws = new WebSocket('wss://localhost:8000/api/v1/ws?token=<jwt_token>');
// Option 2: First message after connect
ws.send(JSON.stringify({ type: 'auth', token: '<jwt_token>' }));
Client-to-Server Messages#
Subscribe to Session Events#
{
"type": "subscribe",
"data": {
"session_id": "660e8400-e29b-41d4-a716-446655440001",
"events": ["session.*", "conversation.*"]
}
}
Event patterns: * (all), session.* (session events), session.started
(specific event).
Unsubscribe#
{
"type": "unsubscribe",
"data": {
"session_id": "660e8400-e29b-41d4-a716-446655440001"
}
}
Control Commands#
{
"type": "command",
"id": "cmd_123",
"data": {
"session_id": "660e8400-e29b-41d4-a716-446655440001",
"command": "session.pause",
"parameters": {}
}
}
Available Commands:
| Command | Parameters | Description |
|---|---|---|
session.start |
-- | Start pending session |
session.pause |
-- | Pause active session |
session.resume |
-- | Resume paused session |
session.end |
-- | End session |
audio.mute |
-- | Mute AI microphone |
audio.unmute |
-- | Unmute AI microphone |
video.enable |
-- | Enable AI camera |
video.disable |
-- | Disable AI camera |
ai.interrupt |
-- | Interrupt AI speech |
ai.set_mode |
{ mode: "listening" } |
Set AI behavior mode |
tool.execute |
{ tool_id, params } |
Execute a tool |
persona.switch |
{ persona_id } |
Switch to different persona |
Ping#
{
"type": "ping",
"timestamp": "2026-01-31T10:00:00.000Z"
}
Server-to-Client Messages#
Session Events#
{
"type": "event",
"data": {
"event": "session.started",
"session_id": "660e8400-e29b-41d4-a716-446655440001",
"timestamp": "2026-01-31T10:05:00.000Z",
"payload": {
"persona_id": "550e8400-e29b-41d4-a716-446655440000",
"platform": "zoom"
}
}
}
Event Types:
| Event | Payload |
|---|---|
session.started |
{ persona_id, platform } |
session.ended |
{ duration_seconds, turns } |
session.paused |
{ reason } |
session.resumed |
-- |
session.error |
{ error_code, message } |
session.state_changed |
{ old_state, new_state } |
meeting.joining |
{ platform, meeting_url } |
meeting.joined |
{ meeting_id, participants } |
meeting.left |
{ reason } |
meeting.participant_joined |
{ participant_id, name } |
meeting.participant_left |
{ participant_id, name } |
conversation.turn_started |
{ turn_id, speaker } |
conversation.turn_ended |
{ turn_id, duration_ms } |
conversation.message |
{ role, content, turn_id } |
ai.thinking |
-- |
ai.speaking |
{ text } |
ai.listening |
-- |
ai.idle |
-- |
tool.executing |
{ tool_id, tool_name } |
tool.completed |
{ tool_id, result } |
tool.error |
{ tool_id, error } |
emotion.detected |
{ emotion, confidence } |
Transcript Events#
Real-time speech transcription updates:
{
"type": "transcript",
"data": {
"session_id": "660e8400-e29b-41d4-a716-446655440001",
"segments": [
{
"speaker": "user",
"text": "Can you tell me about pricing?",
"start_time_ms": 1500,
"end_time_ms": 2100,
"confidence": 0.95,
"is_final": true
}
]
}
}
Metrics Events#
Real-time performance metrics:
{
"type": "metrics",
"data": {
"session_id": "660e8400-e29b-41d4-a716-446655440001",
"timestamp": "2026-01-31T10:05:00.000Z",
"metrics": {
"avatar_fps": 30,
"avatar_latency_ms": 22,
"voice_latency_ms": 85,
"perception_latency_ms": 15,
"end_to_end_latency_ms": 420,
"gpu_memory_usage_mb": 7500
}
}
}
Command Acknowledgment#
{
"type": "ack",
"data": {
"command_id": "cmd_123",
"success": true,
"result": {}
}
}
Error#
{
"type": "error",
"data": {
"code": "INVALID_COMMAND",
"message": "Unknown command: session.invalid",
"correlation_id": "req_xxxxxxxx"
}
}
Connection Management#
- Heartbeat: Send
pingevery 30 seconds to maintain the connection - Reconnection: Implement exponential backoff (1s, 2s, 4s, 8s, max 30s)
- Connection limits: Vary by tier (Free: 5, Pro: 20, Enterprise: 100)
Health and Status#
Health Check#
GET /health
Response: 200 OK
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2026-01-31T10:00:00Z"
}
Readiness Probe#
GET /ready
Returns 200 OK when all service dependencies (database, Redis, Qdrant) are
available.
Liveness Probe#
GET /live
Returns 200 OK when the service process is alive.
Error Handling#
All errors follow a consistent format:
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Session with ID 'xxx' not found",
"details": {
"resource_type": "session",
"resource_id": "xxx"
},
"correlation_id": "req_xxxxxxxxxxxxxxxx"
}
}
Error Codes#
| HTTP Status | Code | Description |
|---|---|---|
| 400 | BAD_REQUEST |
Invalid request format |
| 400 | VALIDATION_ERROR |
Field validation failed |
| 401 | UNAUTHORIZED |
Authentication required |
| 403 | FORBIDDEN |
Insufficient permissions |
| 404 | RESOURCE_NOT_FOUND |
Resource does not exist |
| 409 | CONFLICT |
Resource state conflict |
| 422 | UNPROCESSABLE_ENTITY |
Semantic validation failed |
| 429 | RATE_LIMITED |
Too many requests |
| 500 | INTERNAL_ERROR |
Server error |
| 503 | SERVICE_UNAVAILABLE |
Service temporarily down |
Rate Limiting#
API requests are rate limited per API key or user token:
| Tier | Requests/Minute | Requests/Hour |
|---|---|---|
| Free | 60 | 1,000 |
| Pro | 300 | 10,000 |
| Enterprise | 1,000 | 50,000 |
Rate Limit Headers:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1706698800
When rate limited, the API returns 429 Too Many Requests with a Retry-After
header indicating the number of seconds to wait.
Endpoint Summary#
REST Endpoints#
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/auth/token |
Get JWT token |
| POST | /api/v1/auth/refresh |
Refresh JWT token |
| POST | /api/v1/sessions |
Create session |
| GET | /api/v1/sessions |
List sessions |
| GET | /api/v1/sessions/{id} |
Get session |
| POST | /api/v1/sessions/{id}/start |
Start session |
| POST | /api/v1/sessions/{id}/join-meeting |
Join video conference |
| POST | /api/v1/sessions/{id}/pause |
Pause session |
| POST | /api/v1/sessions/{id}/resume |
Resume session |
| POST | /api/v1/sessions/{id}/end |
End session |
| DELETE | /api/v1/sessions/{id} |
Delete session |
| GET | /api/v1/sessions/metrics |
Get session metrics |
| POST | /api/v1/personas |
Create persona |
| GET | /api/v1/personas |
List personas |
| GET | /api/v1/personas/{id} |
Get persona |
| PATCH | /api/v1/personas/{id} |
Update persona |
| DELETE | /api/v1/personas/{id} |
Delete persona |
| POST | /api/v1/personas/{id}/activate |
Activate persona |
| POST | /api/v1/personas/{id}/deactivate |
Deactivate persona |
| POST | /api/v1/personas/{id}/clone |
Clone persona |
| POST | /api/v1/knowledge/documents/upload |
Upload document |
| GET | /api/v1/knowledge/documents |
List documents |
| GET | /api/v1/knowledge/documents/{id} |
Get document |
| DELETE | /api/v1/knowledge/documents/{id} |
Delete document |
| POST | /api/v1/knowledge/documents/{id}/reprocess |
Reprocess document |
| POST | /api/v1/knowledge/search |
Semantic search |
| POST | /api/v1/tools |
Register tool |
| GET | /api/v1/tools |
List tools |
| GET | /api/v1/tools/{id} |
Get tool |
| GET | /api/v1/tools/{id}/schema |
Get tool schema |
| PATCH | /api/v1/tools/{id} |
Update tool |
| DELETE | /api/v1/tools/{id} |
Delete tool |
| POST | /api/v1/tools/{id}/test |
Test tool |
| POST | /api/v1/tools/{id}/activate |
Activate tool |
| POST | /api/v1/tools/{id}/deactivate |
Deactivate tool |
| POST | /api/v1/webhooks |
Create webhook |
| GET | /api/v1/webhooks |
List webhooks |
| GET | /api/v1/webhooks/{id} |
Get webhook |
| PATCH | /api/v1/webhooks/{id} |
Update webhook |
| DELETE | /api/v1/webhooks/{id} |
Delete webhook |
| POST | /api/v1/webhooks/{id}/test |
Test webhook |
| GET | /api/v1/webhooks/{id}/deliveries |
View delivery history |
| GET | /health |
Health check |
| GET | /ready |
Readiness probe |
| GET | /live |
Liveness probe |
WebSocket Endpoints#
| Path | Description |
|---|---|
/api/v1/ws |
General WebSocket connection |
/api/v1/ws/sessions/{session_id} |
Session-specific connection |