Direct API Guide

Generate AI-powered concept maps with a single API call

POST /api/direct/map

Choose Your Method

Two ways to generate concept maps - click a card to see details:

Structural Method

Use when you know the exact subject hierarchy

domain + subdomain + key

FreeText Method

Use when you have a problem or learning goal

problem description

Class Management

Create classes with curricula (up to 30 concepts), enroll students, track progress

curriculum + enrollment

Quick Examples

// 1. Structural - when you know the topic
POST /api/direct/map
{ "domain": "Mathematics", "subdomain": "Algebra", "key": "Quadratic Equations" }

// 2. FreeText - when you have a problem
POST /api/direct/map
{ "problem": "How to build a recommendation system for e-commerce" }

// 3. Generate Curriculum (up to 30 concepts)
POST /api/map/curriculum
{ "domain": "Computer Science", "subdomain": "AI", "concepts": ["Neural Networks"], "targetCount": 20 }

// 4. Batch-generate maps for many concepts at once (50% cost, async)
POST /api/curriculum/batch-generate
{ "classId": "cls_abc", "concepts": [{ "id": "1", "label": "Neural Networks" }] }

// 5. Create Class (requires teacher role)
POST /api/classes
{ "name": "Intro to AI", "domain": "Computer Science", "subdomain": "AI" }

// 6. Student joins with enrollment code
POST /api/classes/join
{ "code": "ABC123" }

Try Compose Tool Full API Docs JSON Schema

Structural Method

Use when you know the exact domain/topic hierarchy (like a textbook organization).

Identify Your Topic Hierarchy

Break down your topic into three levels:

"domain":    "Mathematics"         // Subject area
"subdomain": "Algebra"             // Chapter/topic
"key":       "Quadratic Equations" // Specific concept

Build Your Request

{
  "domain": "Mathematics",
  "subdomain": "Algebra",
  "key": "Quadratic Equations"
}

Add Context (Optional)

{
  "domain": "Mathematics",
  "subdomain": "Algebra",
  "key": "Quadratic Equations",
  "context": "Focus on factoring methods, suitable for high school"
}

Send Request

curl -X POST /api/direct/map \
  -H "Content-Type: application/json" \
  -d '{"domain":"Mathematics","subdomain":"Algebra","key":"Quadratic Equations"}'

FreeText Method

Use when you have a problem to solve or a learning goal - AI identifies the key concepts.

Describe Your Problem/Goal

Write a natural description of what you want to learn:

"problem": "I need to understand how to build a recommendation system for an e-commerce website"

Build Your Request

{
  "problem": "I need to understand how to build a recommendation system for an e-commerce website"
}

Add Context (Optional)

{
  "problem": "I need to build a recommendation system for e-commerce",
  "context": "Focus on collaborative filtering and Python implementation"
}

Specify Language (Optional)

Add "lang" to the JSON body to get the map in a specific language:

{
  "problem": "I need to build a recommendation system for e-commerce",
  "lang": "fr"
}

Supported: en, es, fr, zh, de, pt, ar, hi, ja, ko, ru, it, nl, tr

Send Request

curl -X POST /api/direct/map \
  -H "Content-Type: application/json" \
  -d '{"problem":"How to build a recommendation system for e-commerce","lang":"fr"}'

Optional Fields

These fields work with both Structural and FreeText methods:

"context"

Additional instructions to tailor the map

"email"

User email for tracking and auto-login

"name"

User display name for attribution

"config"

Override LLM/storage settings

Full Example

{
  "domain": "Computer Science",
  "subdomain": "Machine Learning",
  "key": "Neural Networks",
  "context": "Focus on practical PyTorch implementation",
  "email": "student@university.edu",
  "name": "Jane Smith"
}

Query Parameters

?skipCache=true

Force regeneration (bypass cache)

?includeLearningPath=false

Skip learning path generation

Headers

X-LLM-Provider

azure | openai | anthropic

X-Language

en | es | zh | fr | etc.

X-API-Key

Your API key (if auth enabled)

Configuration Override

Bring your own API keys or override server defaults. All fields are optional.

LLM Configuration

{
  "config": {
    "llm": {
      "provider": "openai",           // azure | openai | anthropic
      "openaiApiKey": "sk-...",       // Your OpenAI key
      "anthropicApiKey": "sk-ant-...", // Your Anthropic key
      "azureApiKey": "...",           // Your Azure key
      "azureEndpoint": "https://...",  // Azure endpoint
      "azureDeployment": "gpt-4"       // Deployment name
    }
  }
}

Example: Use Your Own OpenAI Key

{
  "domain": "Mathematics",
  "subdomain": "Algebra",
  "key": "Quadratic Equations",
  "config": {
    "llm": {
      "provider": "openai",
      "openaiApiKey": "sk-your-api-key-here"
    }
  }
}

Feature Flags

# Batch curriculum generation (Phase 4)
ENABLE_BATCH_CURRICULUM=true         // set false to disable POST /api/curriculum/batch-generate
ANTHROPIC_MODEL_BATCH=claude-haiku-4-5-20251001  // model used for batch jobs

# Extended Thinking for Q2L scoring (anthropic provider only)
ENABLE_EXTENDED_THINKING=true       // set false to use standard Q2L scoring
EXTENDED_THINKING_BUDGET=10000      // max thinking tokens per Q2L score call

# Primary model (used for real-time map generation)
ANTHROPIC_MODEL_PRIMARY=claude-sonnet-4-6

View Current Config

Response Format

The API returns a concept map with nodes, edges, and learning path:

{
  "success": true,
  "mapId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "structural",  // or "freeText"
  "map": {
    "nodes": [
      { "id": "node-1", "label": "Quadratic Equations", "type": "concept", "isCenter": true },
      { "id": "node-2", "label": "Factoring", "type": "skill" },
      { "id": "node-3", "label": "Linear Equations", "type": "prerequisite" }
    ],
    "edges": [
      { "from": "node-3", "to": "node-1", "type": "requires" },
      { "from": "node-2", "to": "node-1", "type": "enables" }
    ],
    "learningPath": ["node-3", "node-2", "node-1"],
    "learningPhases": [
      { "name": "Foundations", "nodeIds": ["node-3"] },
      { "name": "Skills", "nodeIds": ["node-2"] },
      { "name": "Core", "nodeIds": ["node-1"] }
    ]
  },
  "input": { "domain": "Mathematics", "subdomain": "Algebra", "key": "Quadratic Equations" }
}

Node Types

"concept"

Theoretical knowledge (rectangle)

"skill"

Practical ability (pill shape)

"prerequisite"

Foundational knowledge (hexagon)

Edge Types

"requires"

Target needs source first

"enables"

Source leads to target

"related"

General relationship

"special-case"

Source is a type of target

Class Management

Create classes with curricula containing up to 30 concepts/skills. Teachers can enroll students and track learning progress.

1. Generate Curriculum

First, generate a curriculum with up to 30 concepts:

POST /api/map/curriculum
{
  "domain": "Computer Science",
  "subdomain": "Machine Learning",
  "concepts": ["Neural Networks", "Deep Learning"],
  "targetCount": 20  // max 30
}

2. Create a Class

Create a class (requires teacher role):

POST /api/classes
Authorization: Bearer <jwt-token>
{
  "name": "Introduction to AI",
  "description": "Learn AI fundamentals",
  "domain": "Computer Science",
  "subdomain": "Artificial Intelligence"
}

Response includes a 6-character enrollmentCode for students to join.

3. Save Curriculum to Class

POST /api/classes/:classId/curriculum
Authorization: Bearer <jwt-token>
{
  "curriculum": {
    "nodes": [...],
    "edges": [...],
    "learningPath": [...]
  }
}

4. Student Enrollment

Students join with the enrollment code:

POST /api/classes/join
Authorization: Bearer <jwt-token>
{
  "code": "ABC123"
}

5. Batch-Generate Curriculum Maps (Async, 50% Cost)

Submit a list of concepts and let the server generate all maps asynchronously using the Anthropic Batch API. Results are written to GCS when complete.

POST /api/curriculum/batch-generate
Authorization: Bearer <jwt-token>  (teacher or admin role required)
{
  "classId": "cls_abc123",
  "concepts": [
    { "id": "1", "label": "Neural Networks" },
    { "id": "2", "label": "Gradient Descent" }
  ]
}

// Response (immediate)
{ "batchId": "msgbatch_...", "status": "processing", "totalConcepts": 2, "message": "Batch submitted..." }

Poll for completion:

GET /api/curriculum/batch-status/:batchId?classId=cls_abc123
// Returns: { batchId, status: "processing"|"completed", requestCounts, succeeded, failed }

GET /api/curriculum/batch-results/:batchId?classId=cls_abc123
// Returns: { status, succeeded, failed, results: [{ conceptId, gcsPath }] }

All Class Endpoints

POST /api/classes

Create class (teacher)

GET /api/classes

List your classes

GET /api/classes/:id

Get class details

POST /api/classes/join

Join with code

POST /api/classes/:id/curriculum

Save curriculum

DELETE /api/classes/:id

Delete class

GET /api/classes/:id/progress

Get learning progress

GET /api/classes/:id/all-progress

All students progress

POST /api/curriculum/batch-generate

Async batch map generation (teacher)

GET /api/curriculum/batch-status/:id

Poll batch job status

GET /api/curriculum/batch-results/:id

Retrieve completed batch maps

💡 Tip: Use AI Suggestions

The Compose Tool provides AI-powered suggestions for curriculum topics and class structure. Try it for an easier workflow!

Try Compose Tool Full API Docs

Learning Analytics

myKE embeds stealth assessment across 128 learner behaviors organized into 16 interaction contexts. Every API-generated map feeds into this pipeline — click a node, send a chat message, or attempt an assessment and the event is captured, modelled, and reflected back as a composite learner profile.

128

Observable behaviors

Learner models

Interaction contexts

Bloom's levels measured

Analytics events flow through POST /api/analytics/events (batched, 5 s / 50 events). Learner profiles are read via GET /api/analytics/profile/:userId. xAPI statements are delivered to POST /api/xapi/statement.

Open Full Page Full API Docs