{"name":"myKnowledgeExplorer Direct API","version":"1.1.0","description":"Generate AI-powered concept maps using Structural (domain/subdomain/key) or FreeText (problem description) methods","baseUrl":"https://ke.skoonline.org/api/direct","authentication":{"required":false,"method":"API Key via X-API-Key header or Authorization: Bearer <key>"},"generationMethods":{"structural":{"description":"Use when you know the exact domain/topic hierarchy","fields":{"domain":{"type":"string","required":true,"description":"Subject area (e.g., \"Mathematics\")"},"subdomain":{"type":"string","required":true,"description":"Specific topic area (e.g., \"Algebra\")"},"key":{"type":"string","required":true,"description":"Concept or skill to map (e.g., \"Quadratic Equations\")"}}},"freeText":{"description":"Use when you have a problem or goal - AI identifies the key concepts","fields":{"problem":{"type":"string","required":true,"description":"Problem or learning goal description"}}}},"commonFields":{"_note":"These optional fields work with BOTH structural and freeText methods","lang":{"type":"string","required":false,"description":"Language code for map content (e.g., \"fr\", \"es\", \"zh\"). Takes priority over X-Language header and ?lang= query param.","values":["en","es","fr","zh","de","pt","ar","hi","ja","ko","ru","it","nl","tr"],"default":"en"},"context":{"type":"string","required":false,"description":"Additional instructions to tailor the map (e.g., \"Focus on beginner concepts\")"},"email":{"type":"string","required":false,"description":"User email for tracking/attribution and auto-provisioning"},"name":{"type":"string","required":false,"description":"User display name for tracking/attribution"},"config":{"type":"object","required":false,"description":"Override default configuration. All fields are optional - uses server .env defaults if not provided.","schema":{"llm":{"provider":{"description":"LLM provider to use","values":["azure","openai","anthropic"],"default":"azure","envVar":"LLM_PROVIDER"},"openaiApiKey":{"description":"OpenAI API key","configured":true,"envVar":"OPENAI_API_KEY"},"anthropicApiKey":{"description":"Anthropic API key","configured":true,"envVar":"ANTHROPIC_API_KEY"},"azureApiKey":{"description":"Azure OpenAI API key","configured":true,"envVar":"AZURE_OPENAI_API_KEY"},"azureEndpoint":{"description":"Azure OpenAI endpoint URL","configured":true,"envVar":"AZURE_OPENAI_ENDPOINT"},"azureDeployment":{"description":"Azure OpenAI deployment name","default":"gpt-4.1-mini","envVar":"AZURE_OPENAI_DEPLOYMENT"},"azureApiVersion":{"description":"Azure OpenAI API version","default":"2024-08-01-preview","envVar":"AZURE_OPENAI_API_VERSION"}},"xapi":{"endpoint":{"description":"xAPI LRS endpoint URL","configured":true,"envVar":"XAPI_ENDPOINT"},"username":{"description":"xAPI LRS username","configured":true,"envVar":"XAPI_USERNAME"},"password":{"description":"xAPI LRS password","configured":true,"envVar":"XAPI_PASSWORD"}},"gcs":{"bucketName":{"description":"Google Cloud Storage bucket name","configured":true,"envVar":"GCS_BUCKET_NAME"},"projectId":{"description":"Google Cloud project ID","configured":true,"envVar":"GCS_PROJECT_ID"},"keyFile":{"description":"Path to GCS service account key file","configured":false,"envVar":"GCS_KEY_FILE"}}}}},"endpoints":[{"method":"POST","path":"/map","description":"Generate a concept map using either Structural or FreeText method"},{"method":"GET","path":"/map?json={...}","description":"Generate a concept map via GET with JSON query parameter"},{"method":"GET","path":"/map?help","description":"Agent-friendly API instructions (concise format for code agents)"},{"method":"GET","path":"/health","description":"Check API health status"},{"method":"GET","path":"/docs","description":"This documentation"}],"classManagement":{"_note":"Class management endpoints require authentication. Use /api/direct/map with email to auto-provision as teacher first.","curriculumLimits":{"maxConcepts":30,"description":"A class curriculum can contain up to 30 concepts/skills organized in a learning path"},"baseUrl":"https://ke.skoonline.org/api/classes","endpoints":[{"method":"POST","path":"/api/classes","description":"Create a new class (teacher/admin only)","requiresAuth":true,"requiredRole":"teacher","body":{"name":{"type":"string","required":true,"description":"Class name (min 2 characters)"},"description":{"type":"string","required":false,"description":"Class description"},"subject":{"type":"string","required":false,"description":"Subject area"},"domain":{"type":"string","required":false,"description":"Learning domain"},"subdomain":{"type":"string","required":false,"description":"Learning subdomain"}},"response":{"success":true,"class":{"id":"uuid","name":"Class Name","enrollmentCode":"6-char code","teacherEmail":"teacher@example.com","students":[],"curriculum":null}}},{"method":"GET","path":"/api/classes","description":"List classes for current user (teachers see their classes, learners see enrolled classes)","requiresAuth":true},{"method":"GET","path":"/api/classes/:id","description":"Get class details","requiresAuth":true},{"method":"POST","path":"/api/map/curriculum","description":"Generate a curriculum with up to 30 concepts/skills","requiresAuth":false,"body":{"domain":{"type":"string","required":true,"description":"Subject domain (e.g., \"Computer Science\")"},"subdomain":{"type":"string","required":true,"description":"Topic area (e.g., \"Machine Learning\")"},"concepts":{"type":"array","required":true,"description":"Initial concepts to build curriculum around"},"targetCount":{"type":"number","required":false,"description":"Target number of concepts (default: 15, max: 30)"},"llmProvider":{"type":"string","required":false,"description":"azure|openai|anthropic"}},"response":{"curriculum":{"nodes":"[array of concept nodes with id, label, type, description]","edges":"[array of relationships between concepts]","learningPath":"[ordered array of node IDs for learning sequence]","learningPhases":"[grouped phases for progressive learning]"}}},{"method":"POST","path":"/api/classes/:id/curriculum","description":"Save generated curriculum to a class","requiresAuth":true,"requiredRole":"teacher","body":{"curriculum":{"type":"object","description":"{ nodes: [...], edges: [...], learningPath: [...] }"}}},{"method":"POST","path":"/api/classes/join","description":"Join a class with enrollment code (any authenticated user)","requiresAuth":true,"body":{"code":{"type":"string","required":true,"description":"6-character enrollment code"}}},{"method":"DELETE","path":"/api/classes/:id","description":"Delete a class (teacher only)","requiresAuth":true,"requiredRole":"teacher"}],"examples":{"generateCurriculum":{"description":"Generate a curriculum with up to 30 concepts for a topic","curl":"curl -X POST https://ke.skoonline.org/api/map/curriculum \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\":\"Computer Science\",\"subdomain\":\"Machine Learning\",\"concepts\":[\"Neural Networks\",\"Deep Learning\"],\"targetCount\":20}'","body":{"domain":"Computer Science","subdomain":"Machine Learning","concepts":["Neural Networks","Deep Learning"],"targetCount":20}},"createClass":{"description":"Create a new class (requires teacher role)","curl":"curl -X POST https://ke.skoonline.org/api/classes \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-jwt-token>\" \\\n  -d '{\"name\":\"Introduction to AI\",\"description\":\"Learn AI fundamentals\",\"domain\":\"Computer Science\",\"subdomain\":\"Artificial Intelligence\"}'","body":{"name":"Introduction to AI","description":"Learn AI fundamentals","domain":"Computer Science","subdomain":"Artificial Intelligence"}},"saveCurriculumToClass":{"description":"Save a generated curriculum to a class","curl":"curl -X POST https://ke.skoonline.org/api/classes/<class-id>/curriculum \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-jwt-token>\" \\\n  -d '{\"curriculum\":{\"nodes\":[...],\"edges\":[...],\"learningPath\":[...]}}'"},"joinClass":{"description":"Join a class with enrollment code","curl":"curl -X POST https://ke.skoonline.org/api/classes/join \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-jwt-token>\" \\\n  -d '{\"code\":\"ABC123\"}'","body":{"code":"ABC123"}}}},"headers":{"X-API-Key":"Your API key (if authentication enabled)","X-LLM-Provider":"azure|openai|anthropic (default: azure)","X-Language":"Language code (default: en)"},"queryParams":{"skipCache":"true to force regeneration","includeLearningPath":"false to skip learning path"},"optionalIntegrations":{"storage":{"description":"Google Cloud Storage for persistent map storage","envVars":["GCS_BUCKET_NAME","GCS_PROJECT_ID","GOOGLE_APPLICATION_CREDENTIALS"],"fallback":"In-memory storage (maps lost on restart)"},"learningRecords":{"description":"xAPI Learning Record Store for tracking learning interactions","envVars":["XAPI_ENDPOINT","XAPI_USERNAME","XAPI_PASSWORD"],"fallback":"Local in-memory store (limited to 500 statements per user)"}},"examples":{"structural":{"curl":"curl -X POST https://ke.skoonline.org/api/direct/map \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\":\"Mathematics\",\"subdomain\":\"Algebra\",\"key\":\"Quadratic Equations\",\"context\":\"Focus on factoring\"}'","body":{"domain":"Mathematics","subdomain":"Algebra","key":"Quadratic Equations","context":"Focus on factoring"}},"freeText":{"curl":"curl -X POST https://ke.skoonline.org/api/direct/map \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"problem\":\"I need to build a recommendation system for e-commerce\",\"context\":\"Focus on collaborative filtering\"}'","body":{"problem":"I need to build a recommendation system for e-commerce","context":"Focus on collaborative filtering"}},"javascript":"// Structural method\nconst response = await fetch('https://ke.skoonline.org/api/direct/map', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ domain: 'Mathematics', subdomain: 'Algebra', key: 'Quadratic Equations' })\n});\n\n// FreeText method\nconst response = await fetch('https://ke.skoonline.org/api/direct/map', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ problem: 'How to optimize database queries for high-traffic apps' })\n});","python":"import requests\n\n# Structural method\nresponse = requests.post('https://ke.skoonline.org/api/direct/map',\n    json={'domain': 'Mathematics', 'subdomain': 'Algebra', 'key': 'Quadratic Equations'})\n\n# FreeText method\nresponse = requests.post('https://ke.skoonline.org/api/direct/map',\n    json={'problem': 'How to build a REST API with authentication'})","withConfigOverride":{"description":"Using your own LLM API key (overrides server defaults)","body":{"domain":"Computer Science","subdomain":"Machine Learning","key":"Neural Networks","config":{"llm":{"provider":"openai","openaiApiKey":"sk-your-api-key-here"}}},"curl":"curl -X POST https://ke.skoonline.org/api/direct/map \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\":\"Computer Science\",\"subdomain\":\"Machine Learning\",\"key\":\"Neural Networks\",\"config\":{\"llm\":{\"provider\":\"openai\",\"openaiApiKey\":\"sk-your-key\"}}}'"}},"interactiveTools":{"compose":{"url":"https://ke.skoonline.org/api/direct/compose","description":"Interactive form to build and test API requests with live JSON preview"},"howTo":{"url":"https://ke.skoonline.org/api/direct/mapHowTo","description":"Step-by-step guide with tabs for Structural, FreeText, Curriculum, and Class workflows"},"schema":{"url":"https://ke.skoonline.org/api/direct/map?help","description":"Agent-friendly API schema (concise JSON format for code agents)"}},"workflow":{"mapGeneration":"1. POST /api/direct/map with domain/subdomain/key OR problem → Returns concept map with nodes, edges, learningPath","curriculum":"1. POST /api/direct/suggest (mode: curriculum) → Get AI suggestions\n2. POST /api/map/curriculum → Generate full curriculum (up to 30 concepts)","classCreation":"1. Login as teacher\n2. POST /api/classes → Create class (get enrollmentCode)\n3. POST /api/map/curriculum → Generate curriculum\n4. POST /api/classes/:id/curriculum → Attach curriculum\n5. Share enrollmentCode with students","studentEnrollment":"1. Login as student\n2. POST /api/classes/join with enrollmentCode → Join class\n3. Access curriculum at /learner/classes"}}