# Psyche API Reference

> 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](#authentication)
2. [Sessions API](#sessions-api)
3. [Personas API](#personas-api)
4. [Knowledge Base API](#knowledge-base-api)
5. [Tools API](#tools-api)
6. [Webhooks API](#webhooks-api)
7. [WebSocket API](#websocket-api)
8. [Health and Status](#health-and-status)
9. [Error Handling](#error-handling)
10. [Rate Limiting](#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          |

### Semantic Search

```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

```
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  |
