ai-gateway/api_documentation.md

# Storyline AI Gateway - API Documentation

This document provides technical details for interacting with the Storyline AI Gateway. All API endpoints are versioned under `/api/v1` except for administrative/internal functions.

---

## 🔐 Authentication Types

### 1. Master API Key (Administrative)
Used for managing modules or as a global override.
- **Header**: `X-API-Key`
- **Value**: Found in your `.env` file as `API_KEY`.

### 2. Module Secret Key (Production)
Generated per e-learning module in the Admin Dashboard.
- **Header**: `X-API-Key`
- **Value**: The specific key created for your Storyline project.

### 3. JWT Token (Dashboard Only)
Used by the HTML Admin interface.
- **Header**: `Authorization`
- **Value**: `Bearer <token_from_login>`

---

## 🤖 LLM Endpoints (Public API)

These are the endpoints you call from your Articulate Storyline JavaScript triggers.

### 1. Gemini Chat
Processes requests using the Google Gemini 2.0 Flash model.
- **URL**: `http://localhost:8191/api/v1/gemini/chat`
- **Method**: `POST`
- **Headers**: `X-API-Key: <your_key>`

**Sample Payload:**
```json
{
  "prompt": "Explain the concept of 'Growth Mindset' for a new employee.",
  "context": "Onboarding Module 2024"
}
```

### 2. OpenAI Chat
Processes requests using GPT-3.5-Turbo (or configured OpenAI model).
- **URL**: `http://localhost:8191/api/v1/openai/chat`
- **Method**: `POST`
- **Headers**: `X-API-Key: <your_key>`

**Sample Payload:**
```json
{
  "prompt": "Summarize the safety protocols for the warehouse.",
  "context": "Safety Compliance Course"
}
```

### 3. Health Check
Verify if the gateway is online.
- **URL**: `http://localhost:8191/api/v1/storyline/health`
- **Method**: `GET`
- **Headers**: No Auth required.

---

## 🎙️ Gemini Live Endpoints (Live Practice)

Used by the Live Practice plugin template for real-time voice conversations.

### 4. Generate Live Ephemeral Token
Exchanges the module API key for a short-lived token the browser can use to open a direct WebSocket to Gemini Live. The server API key is never exposed to the client.
- **URL**: `http://localhost:8191/api/v1/gemini/live-token`
- **Method**: `POST`
- **Headers**: `X-API-Key: <your_key>`

**Request Payload:**
```json
{
  "model": "gemini-2.0-flash-live-001",
  "system_instruction": "You are a customer service representative named Alex...",
  "voice_name": "Puck"
}
```

**Response:**
```json
{
  "token": "ephemeral-token-value",
  "expires_at": "2026-04-02T01:00:00Z",
  "websocket_uri": "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent"
}
```

The client connects to the WebSocket URI with `?key={token}` appended.

---

### 5. Score Conversation
Evaluates a completed conversation transcript against a scorecard using Gemini Flash with structured JSON output.
- **URL**: `http://localhost:8191/api/v1/gemini/score`
- **Method**: `POST`
- **Headers**: `X-API-Key: <your_key>`

**Request Payload:**
```json
{
  "transcript": [
    { "role": "assistant", "text": "Hi, how can I help you today?" },
    { "role": "user", "text": "I have a problem with my order." }
  ],
  "scorecard": {
    "criteria": [
      {
        "name": "Greeting Quality",
        "weight": 25,
        "description": "Did the learner greet the customer warmly?",
        "good_example": "Hi there! Thanks for reaching out, I'm happy to help.",
        "poor_example": "What do you want?"
      }
    ]
  },
  "pass_threshold": 70
}
```

**Response:**
```json
{
  "overall_score": 82.5,
  "passed": true,
  "criteria_scores": [
    {
      "name": "Greeting Quality",
      "score": 90,
      "feedback": "The learner greeted warmly and set a positive tone."
    }
  ],
  "positives": [
    "Maintained a professional tone throughout.",
    "Actively listened and acknowledged the customer's concern."
  ],
  "improvements": [
    "Could offer a specific resolution timeline earlier.",
    "Consider using the customer's name for a more personal touch."
  ]
}
```

---

## 🛠️ Management Endpoints (Internal)

These endpoints power the Admin Dashboard. They require a Bearer token or Master Key depending on implementation.

### 1. Login
- **URL**: `http://localhost:8191/auth/login`
- **Method**: `POST`
- **Body**: `multipart/form-data` with `username` and `password`.

### 2. Create New Module
- **URL**: `http://localhost:8191/internal/admin/modules`
- **Method**: `POST`
- **Headers**: `Authorization: Bearer <token>`

**Sample Payload:**
```json
{
  "name": "Warehouse Safety 101",
  "program": "OSHA Compliance",
  "lob": "Logistics",
  "job_code": "WH-OP-2"
}
```

### 3. Rotate Module Key
- **URL**: `http://localhost:8000/internal/admin/modules/{module_id}/rotate`
- **Method**: `POST`
- **Headers**: `Authorization: Bearer <token>`

---

## 📊 Rate Limiting
All productive LLM endpoints are limited to **20 calls per minute**. If exceeded, the API will return:
- **Status**: `429 Too Many Requests`
- **Body**: `{"error": "Rate limit exceeded"}`

---

## 💡 Storyline JavaScript Example

```javascript
const response = await fetch("http://localhost:8000/api/v1/gemini/chat", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_MODULE_SECRET_KEY"
    },
    body: JSON.stringify({
        prompt: "Help me write a professional email response.",
        context: "Communication Skills Module"
    })
});
const data = await response.json();
console.log(data.response);
```