Eve library

Psyche API Reference

Guide

Revision 1

On this page

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#

  1. Authentication
  2. Sessions API
  3. Personas API
  4. Knowledge Base API
  5. Tools API
  6. Webhooks API
  7. WebSocket API
  8. Health and Status
  9. Error Handling
  10. Rate Limiting

Authentication#

All API requests require authentication via JWT tokens or API keys.

JWT Authentication#

http
POST /api/v1/auth/token
Content-Type: application/json

Request:

json
{
  "email": "user@example.com",
  "password": "secure_password"
}

Response: 200 OK

json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access token in subsequent requests:

http
Authorization: Bearer <access_token>

API Key Authentication#

http
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#

http
POST /api/v1/sessions
Content-Type: application/json
Authorization: Bearer <token>

Request:

json
{
  "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

json
{
  "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#

http
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

json
{
  "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#

http
GET /api/v1/sessions/{session_id}
Authorization: Bearer <token>

Response: 200 OK

json
{
  "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#

http
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:

json
{
  "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#

http
GET /api/v1/sessions/metrics
Authorization: Bearer <token>

Response: 200 OK

json
{
  "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#

http
POST /api/v1/personas
Content-Type: application/json
Authorization: Bearer <token>

Request:

json
{
  "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#

http
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#

http
PATCH /api/v1/personas/{persona_id}
Content-Type: application/json
Authorization: Bearer <token>

Supports partial updates:

json
{
  "personality": {
    "friendliness": 0.9
  },
  "voice": {
    "speed": 1.1
  }
}

Persona Actions#

http
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#

http
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 .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

json
{
  "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
http
POST /api/v1/knowledge/search
Content-Type: application/json
Authorization: Bearer <token>

Request:

json
{
  "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

json
{
  "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#

http
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#

http
POST /api/v1/tools
Content-Type: application/json
Authorization: Bearer <token>

Request:

json
{
  "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#

http
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:

json
{
  "parameters": {
    "title": "Demo Meeting",
    "start_time": "2026-02-01T14:00:00Z",
    "duration_minutes": 30
  }
}

Webhooks API#

Configure webhooks for event notifications.

Create Webhook#

http
POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer <token>

Request:

json
{
  "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#

json
{
  "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#

http
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#

text
wss://localhost:8000/api/v1/ws
wss://localhost:8000/api/v1/ws/sessions/{session_id}

Authentication (choose one):

javascript
// 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#

json
{
  "type": "subscribe",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "events": ["session.*", "conversation.*"]
  }
}

Event patterns: * (all), session.* (session events), session.started (specific event).

Unsubscribe#

json
{
  "type": "unsubscribe",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001"
  }
}

Control Commands#

json
{
  "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#

json
{
  "type": "ping",
  "timestamp": "2026-01-31T10:00:00.000Z"
}

Server-to-Client Messages#

Session Events#

json
{
  "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:

json
{
  "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:

json
{
  "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#

json
{
  "type": "ack",
  "data": {
    "command_id": "cmd_123",
    "success": true,
    "result": {}
  }
}

Error#

json
{
  "type": "error",
  "data": {
    "code": "INVALID_COMMAND",
    "message": "Unknown command: session.invalid",
    "correlation_id": "req_xxxxxxxx"
  }
}

Connection Management#

  • Heartbeat: Send ping every 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#

http
GET /health

Response: 200 OK

json
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-01-31T10:00:00Z"
}

Readiness Probe#

http
GET /ready

Returns 200 OK when all service dependencies (database, Redis, Qdrant) are available.

Liveness Probe#

http
GET /live

Returns 200 OK when the service process is alive.


Error Handling#

All errors follow a consistent format:

json
{
  "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:

http
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