AI Agent API

The AI Agent API (branded as AI API) provides conversational AI capabilities for your applications. It supports text, voice, and image inputs with streaming responses.

Branding

This service is branded as "AI API" in user-facing documentation and marketing materials.

Base URL

All AI Agent endpoints are under:

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

Authentication

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

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

Chat Stream

Stream AI responses in real-time using NDJSON format.

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

Request Body:

{
  "chatId": "chat-123",
  "message": "Explain quantum computing",
  "audio": "base64-encoded-audio", // Optional
  "image": "base64-encoded-image", // Optional
  "imageMimeType": "image/jpeg", // Required if image provided
  "voiceName": "Fenrir", // Optional, default voice
  "responseModality": "text" // "text", "audio", or "text+audio"
}

Response: NDJSON stream

{"type":"text","text":"Quantum"}
{"type":"text","text":" computing"}
{"type":"text","text":" uses"}
{"type":"usage","usage":{"inputTokens":150,"outputTokens":300}}
{"type":"done"}

Response Headers:

• Content-Type: application/x-ndjson; charset=utf-8

Usage Summary

Get aggregated AI usage statistics for your organization.

Endpoint: GET /v1/ai-agent/usage/summary

Query Parameters:

• startDate (optional): Start date (ISO 8601)
• endDate (optional): End date (ISO 8601)

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalSessions": 150,
      "totalTokenCost": 12.50,
      "totalInputTokens": 50000,
      "totalOutputTokens": 75000
    },
    "breakdown": {
      "aiAgent": {
        "sessions": 100,
        "inputTokens": 30000,
        "outputTokens": 50000,
        "cost": 8.00
      },
      "aiTutor": {
        "interactions": 50,
        "inputTokens": 20000,
        "outputTokens": 25000,
        "cost": 4.50
      }
    }
  }
}

Error Codes

Code	Meaning
400	Bad request - missing or invalid parameters
401	Unauthorized - invalid or missing organization ID
402	Insufficient credits
500	Internal server error

Example: Streaming Chat

const response = await fetch('https://api.verriflo.com/v1/ai-agent/chat/stream', {
  method: 'POST',
  headers: {
    'VF-ORG-ID': 'your-org-id',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    chatId: 'chat-123',
    message: 'Explain machine learning',
    responseModality: 'text'
  })
});

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

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.trim()) {
      const data = JSON.parse(line);
      if (data.type === 'text') {
        console.log(data.text); // Stream text
      }
    }
  }
}