Technical Documentation

Complete developer guide with API references, integration examples, and system architecture for building on NuMuN's educational technology platform

Quick Start

5 Minutes

1. Get API Access

Register for developer access and obtain your API credentials

POST /auth/register

2. Install SDK

Add NuMuN SDK to your project for easy integration

npm install @numun/sdk

3. First API Call

Fetch learner recommendations and start building

GET /api/moments/:id

API Reference

Core Learning APIs

GET /api/learners/:id/ledger

Retrieve complete verified skill portfolio with cryptographic proof chains

POST /api/entries

Add new skill entries with supervisor verification and blockchain-style chaining

GET /api/moments/:id

AI-powered personalized learning recommendations (Now/Next/Later)

Authentication & Security

Authorization: Bearer eyJ0eXAi...

JWT tokens with role-based access control and automatic refresh

• 24-hour token expiration with refresh capability
• Role-based permissions (learner/supervisor/employer)
• Rate limiting: 100 requests/minute per key
• CORS support for web applications

System Architecture

NuMuN is built on a modern microservices architecture with four specialized services designed for scalability, security, and real-time performance across educational and workforce development scenarios.

Moments Engine Service

Real-time AI recommendation engine using advanced multi-armed bandit algorithms and contextual learning signals to provide personalized "Now/Next/Later" moments for optimal skill development timing.

Tech Stack: Python 3.11 + FastAPI
ML Stack: TensorFlow, scikit-learn
Caching: Redis with 15-second TTL
Performance: <200ms response time

Ledger Service

Persistent skill tracking service that maintains learner portfolios with verification metadata and institutional endorsements.

Database: PostgreSQL 15 with JSONB
Storage: Replit Object Storage
Indexing: Full-text search on skills
Backup: Multi-region replication

Analytics Service

Real-time learning analytics, cohort tracking, completion metrics, and workforce intelligence insights for educators, employers, and learners.

Database: InfluxDB TimeSeries
Query: GraphQL + REST APIs
Streaming: Apache Kafka
Dashboards: Custom React + Plotly

Integration Gateway

Unified API gateway managing health device integration (Whoop, Apple Health), calendar synchronization, and workplace productivity tool connections.

Gateway: Kong Enterprise
Auth: OAuth 2.0 + OIDC flows
Integrations: 12+ health/productivity APIs
Rate Limiting: Per-service quotas

Data Models & TypeScript Interfaces

Skill Entry Model

interface SkillEntry {
id: string // UUID v4
timestamp: ISO8601 // UTC
learner_id: string
competency: string
rating: number // 1.0-5.0
hours: number // decimal
supervisor_signature: string
previous_hash: string // SHA-256
current_hash: string // SHA-256
institutional_endorsement?: string
}

Moment Recommendation

interface MomentRecommendation {
type: 'now' | 'next' | 'later'
priority: number // 0-100
estimated_minutes: number
energy_requirement: EnergyLevel
skill_gap: string
context_signals: ContextData
confidence: number // 0.0-1.0
learning_path_id?: string
prerequisites: string[]
}

Verification Response

interface VerificationResult {
valid: boolean
credential_id: string
learner_name: string
institution: string
verification_layers: Layer[]
cryptographic_proof: CryptoProof
issued_at: ISO8601
verified_at: ISO8601
}

Analytics Event

interface AnalyticsEvent {
event_type: EventType
user_id: string
session_id: string
timestamp: ISO8601
properties: EventProperties
context: SessionContext
device_info?: DeviceContext
}

SDK Examples & Integration Guides

JavaScript/TypeScript SDK

// Install and initialize
import { NuMuNClient } from '@numun/sdk'
const client = new NuMuNClient({
apiKey: process.env.NUMUN_API_KEY,
environment: 'production'
})
// Get personalized moments
const moments = await client.getMoments(userId)

Python Integration

# Install with pip
pip install numun-python
from numun import NuMuNClient
client = NuMuNClient(api_key="your-key")
ledger = client.get_learner_ledger(user_id)
print(ledger.verification_status)

REST API Example

# Verify a credential
curl -X POST \\
https://api.numun.org/verify \\
-H "Authorization: Bearer $TOKEN" \\
-d "token=numun_cred_2025_..."
# Response includes full verification chain

Webhook Integration

// Express.js webhook handler
app.post('/numun-webhook', (req, res) => {
const event = req.body
if (event.type === 'skill.verified') {
updateUserProfile(event.data)
}
res.status(200).send('OK')
})

Performance Specs & API Limits

API Performance

Response Time<200ms
Uptime SLA99.9%
Data Freshness<15sec
Global CDN12 regions

Rate Limits

Basic Plan100/min
Pro Plan1,000/min
EnterpriseCustom
Burst Allowance2x for 60s

Data Limits

Max Payload10MB
Batch Size1,000 entries
History RetentionUnlimited
Export Size100MB

Developer Resources & Support

Download Center

JavaScript SDKv2.1.0
Python SDKv1.8.3
OpenAPI Specv3.0
Postman CollectionLatest

Community & Support

• Developer Discord Community
• GitHub Discussions & Issues
• Weekly Office Hours (Tuesdays 2PM EST)
• Enterprise Support (24/7)
• Stack Overflow: #numun-api

Status & Monitoring

API Status: Operational
Ledger Service: Operational
Analytics: Operational
Gateway: Maintenance Window

Visit status.numun.org for real-time system status