AI Tutor API

The AI Tutor API provides real-time AI assistance for students during live classroom sessions. It has access to the current class context.

Base URL

All AI Tutor endpoints are under:

https://api.verriflo.com/v1/ai-tutor

Authentication

All requests require your Organization ID in the VF-ORG-ID header:

curl -X POST https://api.verriflo.com/v1/ai-tutor/chat \
  -H "VF-ORG-ID: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{...}'

Chat Endpoints

Send Message

Send a text or audio message to the AI Tutor.

Endpoint: POST /v1/ai-tutor/chat

Request Body:

{
  "roomId": "org_123_class-456",
  "studentUid": "student-789",
  "organizationId": "org_123",
  "text": "What does this equation mean?",
  "audio": "base64-encoded-audio", // Optional
  "responseModality": "text" // "text", "audio", or "both"
}

Response:

{
  "success": true,
  "text": "This equation represents...",
  "audio": "base64-encoded-audio", // If responseModality includes audio
  "usage": {
    "inputTokens": 100,
    "outputTokens": 200
  },
  "requestModality": "text",
  "responseModality": "text"
}

Stream Message

Stream AI Tutor responses in real-time using Server-Sent Events (SSE).

Endpoint: POST /v1/ai-tutor/chat/stream

Request Body: Same as /chat endpoint

Response: SSE stream

data: {"text":"This","usage":null}

data: {"text":" equation","usage":null}

data: {"text":" represents","usage":null}

data: {"usage":{"inputTokens":100,"outputTokens":200}}

data: [DONE]

Response Headers:

• Content-Type: text/event-stream
• Cache-Control: no-cache
• Connection: keep-alive

Class Analytics

Get Class Summary

Get a summary of the class session with top questions and answers.

Endpoint: GET /v1/ai-tutor/summary/:roomId

Response:

{
  "success": true,
  "summary": "Today's class covered algebraic equations...",
  "topQueries": [
    {
      "question": "What does this equation mean?",
      "answer": "This equation represents...",
      "frequency": 5
    }
  ]
}

Get Usage Statistics

Get AI Tutor usage statistics for a specific room.

Endpoint: GET /v1/ai-tutor/usage/:roomId

Response:

{
  "success": true,
  "usage": {
    "inputTokens": 5000,
    "outputTokens": 10000
  }
}

Features

Context Awareness

The AI Tutor has access to the current class context, including:

• Current topic being discussed
• Class metadata and settings
• Previous questions asked in the session

Multi-Modal Support

• Text Input/Output: Standard text-based Q&A
• Audio Input: Students can ask questions via voice
• Audio Output: AI can respond with voice (text-to-speech)

Real-Time Streaming

Stream responses as they're generated for better user experience.

Error Codes

Code	Meaning
400	Bad request - missing required fields (roomId, studentUid, organizationId)
401	Unauthorized - invalid or missing organization ID
402	Insufficient credits
404	Room not found
500	Internal server error

Example: Streaming Chat

const response = await fetch('https://api.verriflo.com/v1/ai-tutor/chat/stream', {
  method: 'POST',
  headers: {
    'VF-ORG-ID': 'your-org-id',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    roomId: 'org_123_class-456',
    studentUid: 'student-789',
    organizationId: 'org_123',
    text: 'What does this equation mean?',
    responseModality: 'text'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let fullText = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const dataStr = line.replace('data: ', '').trim();
      if (dataStr === '[DONE]') continue;
      
      try {
        const parsed = JSON.parse(dataStr);
        if (parsed.text) {
          fullText += parsed.text;
          // Update UI with streaming text
        }
        if (parsed.usage) {
          // Handle usage statistics
        }
      } catch (e) {
        // Ignore parse errors
      }
    }
  }
}

Integration Notes

• AI Tutor is automatically available in live classrooms when enabled
• Students access it through the classroom UI
• All interactions are tracked for analytics and billing
• Usage is aggregated with other AI services in the usage summary endpoint