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:

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

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

---

🛠️ 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:

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

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);