Jump to Section

Overview Auth Quick Start Challenge Gen Evaluator SPI Sim List Embed Curriculum Errors Plans

SPYRAL API v1

Five production-ready AI education APIs — plug SPYRAL's intelligence engine directly into your platform. No ML infrastructure needed.

Base URL: https://tryspyral.com/api/v1 · All responses are JSON · Auth via X-Api-Key: spk_…

Challenge Generator

Generate MCQ, short-answer, and T/F questions for any subject, grade, and curriculum.

Answer Evaluator

Score student answers against a rubric. Returns marks, feedback, and model answer.

SPI Compute

Kalman-filter Student Performance Index from a batch of responses. IRT-calibrated.

Simulation Embed

List and embed SPYRAL's 65+ interactive science simulations via iframe token.

Curriculum Mapper

Map any topic to CBSE, IB, Common Core, Cambridge, or ICSE learning objectives.

Authentication

All endpoints require an API key with the spk_ prefix. Pass it via header (recommended) or query param.

# Recommended — never appears in server logs
curl -H "X-Api-Key: spk_your_key_here" \
  https://tryspyral.com/api/v1/embed/list

# Quick testing only — key may appear in access logs
curl "https://tryspyral.com/api/v1/embed/list?api_key=spk_your_key_here"

Keep your key secret. Never expose spk_ keys in client-side code or commit them to version control. Every response includes a _usage object with your remaining quota.

Quick Start

Generate your first AI quiz in under 60 seconds. Replace spk_YOUR_KEY with your key.

curl -X POST https://tryspyral.com/api/v1/challenge/generate \
  -H "X-Api-Key: spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Physics","grade":"10","topic":"Newton Laws","count":3}'

const API_KEY  = 'spk_YOUR_KEY';
const BASE    = 'https://tryspyral.com/api/v1';

async function spyral(path, body) {
  const res = await fetch(BASE + path, {
    method: body ? 'POST' : 'GET',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`${res.status}`);
  return res.json();
}

// Generate 3 MCQ questions on Newton's Laws
const quiz = await spyral('/challenge/generate', {
  subject: 'Physics', grade: '10', topic: 'Newton Laws', count: 3
});
console.log(quiz.data.questions);

import requests

API_KEY = "spk_YOUR_KEY"
BASE    = "https://tryspyral.com/api/v1"
HEADERS = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

def spyral_post(path, body):
    r = requests.post(BASE + path, json=body, headers=HEADERS)
    r.raise_for_status()
    return r.json()

quiz = spyral_post("/challenge/generate", {
    "subject": "Physics", "grade": "10",
    "topic": "Newton Laws", "count": 3
})
print(quiz["data"]["questions"])

Response Format

Every response follows the same envelope. Every successful response also includes a _usage object.

{
  "success": true,
  "data": { /* payload */ },
  "_usage": {
    "plan":             "growth",
    "calls_this_month": 142,
    "calls_remaining":  49858,
    "limit_per_month":  50000
  }
}

API Endpoints

POST /api/v1/challenge/generate

Generate AI-powered questions for any subject, grade, topic, and curriculum. Supports MCQ, short-answer, true/false, and fill-in-the-blank. Powered by Mistral Large.

Body Parameters

Name	Type	Description
subject *	string	e.g. `Physics`, `Mathematics`, `Biology`
grade *	string	e.g. `9`, `10`, `DP`, `IGCSE`
topic *	string	e.g. `Newton's Laws of Motion`
difficulty	string	`easy` \| `medium` \| `hard` (default: medium)
count	integer	1–20 questions (default: 5)
type	string	`mcq` \| `short-answer` \| `true-false` \| `fill-blank`
curriculum	string	`cbse` \| `ib` \| `common-core` \| `cambridge` \| `icse`
language	string	`en` \| `hi` (default: en)

curl -X POST https://tryspyral.com/api/v1/challenge/generate \
  -H "X-Api-Key: spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Mathematics",
    "grade": "11",
    "topic": "Differentiation",
    "difficulty": "hard",
    "count": 5,
    "type": "mcq",
    "curriculum": "cbse"
  }'

const quiz = await spyral('/challenge/generate', {
  subject: 'Mathematics', grade: '11', topic: 'Differentiation',
  difficulty: 'hard', count: 5, type: 'mcq', curriculum: 'cbse'
});

quiz = spyral_post("/challenge/generate", {
    "subject": "Mathematics", "grade": "11",
    "topic": "Differentiation", "difficulty": "hard",
    "count": 5, "type": "mcq", "curriculum": "cbse"
})

{
  "success": true,
  "data": {
    "subject": "Mathematics", "grade": "11", "count": 5,
    "questions": [
      {
        "question":    "If f(x) = x³ + 2x, then f'(x) is?",
        "options":    ["3x² + 2", "3x²", "x² + 2", "3x + 2"],
        "answer":     "3x² + 2",
        "explanation": "Derivative of x³ is 3x², derivative of 2x is 2.",
        "difficulty": "hard",
        "bloom_level": "apply"
      }
    ]
  }
}

POST /api/v1/evaluate/answer

Score a student's written answer against a question. Returns marks, grade, strengths, improvement areas, and a model answer. Supports custom rubrics.

Body Parameters

Name	Type	Description
question *	string	The original question text
student_answer *	string	The student's written answer
subject	string	Subject context for the evaluator
grade	string	Grade level for appropriate expectations
max_marks	integer	Total marks (default: 10)
rubric	object	Custom rubric — `{"content":40,"explanation":30,"examples":20,"language":10}`

curl -X POST https://tryspyral.com/api/v1/evaluate/answer \
  -H "X-Api-Key: spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Explain Newton'\''s Second Law with an example.",
    "student_answer": "Force equals mass times acceleration. F=ma. If I push a box...",
    "subject": "Physics", "grade": "9", "max_marks": 5
  }'

const result = await spyral('/evaluate/answer', {
  question:       "Explain Newton's Second Law with an example.",
  student_answer: "Force equals mass times acceleration...",
  subject: 'Physics', grade: '9', max_marks: 5
});

{
  "success": true,
  "data": {
    "marks_awarded":    4,
    "max_marks":        5,
    "percentage":       80,
    "grade":            "A",
    "strengths":        ["Correct formula stated", "Good real-world example"],
    "improvements":     ["Define all variables explicitly"],
    "model_answer":     "Newton's Second Law states F = ma...",
    "detailed_feedback": "Excellent understanding of the core concept..."
  }
}

POST /api/v1/spi/compute

Compute a Student Performance Index (SPI) from a batch of question responses using a Kalman filter + IRT calibration. Returns a 0–100 score, grade, and per-competency mastery breakdown.

How it works: Each response is weighted by difficulty (IRT), time taken, and correctness. The Kalman filter reduces noise from daily variance, giving a stable, longitudinal-aware score.

Body Parameters

Name	Type	Description
student_id *	string	Your internal student identifier
responses *	array	Array of response objects (see below)
prior_spi	number	Student's previous SPI (0–100, default: 50 for new students)

Each responses[] item:

Field	Type	Description
is_correct *	boolean	Whether the student answered correctly
difficulty *	number	Question difficulty 0.0 (easy) – 1.0 (hard)
time_taken_secs	integer	Time the student spent on this question
competency	string	Domain label e.g. `critical_thinking`, `algebra`

curl -X POST https://tryspyral.com/api/v1/spi/compute \
  -H "X-Api-Key: spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "stu_abc123",
    "prior_spi": 62,
    "responses": [
      {"is_correct": true,  "difficulty": 0.7, "time_taken_secs": 45, "competency": "algebra"},
      {"is_correct": false, "difficulty": 0.4, "time_taken_secs": 90, "competency": "algebra"},
      {"is_correct": true,  "difficulty": 0.9, "time_taken_secs": 60, "competency": "critical_thinking"}
    ]
  }'

const spi = await spyral('/spi/compute', {
  student_id: 'stu_abc123', prior_spi: 62,
  responses: [
    { is_correct: true,  difficulty: 0.7, time_taken_secs: 45, competency: 'algebra' },
    { is_correct: false, difficulty: 0.4, time_taken_secs: 90, competency: 'algebra' },
    { is_correct: true,  difficulty: 0.9, time_taken_secs: 60, competency: 'critical_thinking' }
  ]
});

{
  "success": true,
  "data": {
    "student_id":           "stu_abc123",
    "spi":                  66.4,
    "prior_spi":            62,
    "delta":                +4.4,
    "grade":                "B",
    "uncertainty":          8.2,
    "questions_processed":  3,
    "competencies": [
      { "name": "algebra",           "mastery": 50, "questions_attempted": 2 },
      { "name": "critical_thinking", "mastery": 100,"questions_attempted": 1 }
    ]
  }
}

GET /api/v1/embed/list

List all available SPYRAL simulations. Filter by subject or grade. Use the id field with the Embed Token endpoint.

Query Parameters

Name	Type	Description
subject	string	Filter by subject e.g. `Physics`, `Mathematics`, `AI`
grade	string	Filter by grade number e.g. `10`

curl -H "X-Api-Key: spk_YOUR_KEY" \
  "https://tryspyral.com/api/v1/embed/list?subject=Physics"

{
  "success": true,
  "data": {
    "total": 3,
    "simulations": [
      { "id": "pendulum", "title": "Simple Pendulum Lab", "subject": "Physics", "grade": "9-12" },
      { "id": "gravity",  "title": "Gravity Simulator",   "subject": "Physics", "grade": "9-12" },
      { "id": "friction", "title": "Friction Explorer",   "subject": "Physics", "grade": "9-12" }
    ]
  }
}

POST /api/v1/embed/token

Generate a time-limited embed token and iframe URL for a SPYRAL simulation. Paste the iframe_snippet directly into your platform.

Body Parameters

Name	Type	Description
simulation_id *	string	ID from `/embed/list` e.g. `pendulum`
student_id	string	Your student identifier (for analytics)
expires_in_minutes	integer	Token lifetime 5–1440 min (default: 60)

curl -X POST https://tryspyral.com/api/v1/embed/token \
  -H "X-Api-Key: spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"simulation_id": "pendulum", "student_id": "stu_abc123", "expires_in_minutes": 90}'

{
  "success": true,
  "data": {
    "simulation_id":     "pendulum",
    "student_id":        "stu_abc123",
    "embed_token":       "a3f9c2d1...",
    "embed_url":         "https://tryspyral.com/nep-workbench/.../SimplePendulumLab.html?embed_token=...",
    "expires_at":        "2026-06-05T11:30:00.000Z",
    "expires_in_minutes": 90,
    "iframe_snippet":    "<iframe src=\"...\" width=\"100%\" height=\"600\" ...></iframe>"
  }
}

POST /api/v1/curriculum/map

Map any topic to one or more curriculum standards. Returns unit, chapter, learning objectives, Bloom's taxonomy levels, prerequisites, and related topics — per curriculum.

Body Parameters

Name	Type	Description
topic *	string	e.g. `Photosynthesis`, `Linear Equations`
subject *	string	e.g. `Biology`, `Mathematics`
grade	string	Optional grade for more precise mapping
curricula	string[]	Array of: `cbse`, `ib`, `common-core`, `cambridge`, `icse` (default: `["cbse"]`)

curl -X POST https://tryspyral.com/api/v1/curriculum/map \
  -H "X-Api-Key: spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Photosynthesis",
    "subject": "Biology",
    "grade": "9",
    "curricula": ["cbse", "cambridge", "ib"]
  }'

const map = await spyral('/curriculum/map', {
  topic: 'Photosynthesis', subject: 'Biology', grade: '9',
  curricula: ['cbse', 'cambridge', 'ib']
});

{
  "success": true,
  "data": {
    "topic": "Photosynthesis", "subject": "Biology", "grade": "9",
    "mappings": [
      {
        "curriculum":           "cbse",
        "curriculum_name":      "CBSE (India)",
        "unit":                 "Life Processes",
        "chapter":              "Chapter 6 — Life Processes",
        "learning_objectives":  ["Define photosynthesis", "Explain the role of chlorophyll"],
        "bloom_levels":         ["remember", "understand", "apply"],
        "prerequisites":        ["Cell structure", "Chloroplast"],
        "related_topics":       ["Respiration", "Nutrition in plants"]
      }
    ],
    "cross_curriculum_note": "IB covers Calvin Cycle in more depth than CBSE at this grade."
  }
}

Error Codes

HTTP	Code	Meaning
401	API_KEY_REQUIRED	No key provided
401	INVALID_KEY_FORMAT	Key does not start with `spk_`
401	INVALID_API_KEY	Key not found, expired, or revoked
403	API_NOT_ENABLED	This API is not enabled on your key — contact sales
429	QUOTA_EXCEEDED	Monthly quota exhausted — upgrade your plan
429	RATE_LIMITED	Per-minute limit hit — slow down and retry
400	MISSING_PARAMS	Required field missing (message names which)
400	INVALID_COUNT / INVALID_TYPE	Parameter out of valid range or enum
502	AI_ERROR	Mistral AI temporarily unavailable — retry in 10s
500	SERVER_ERROR	Unexpected error — contact info@tryspyral.com

Plans & Pricing

All plans include access to all 5 APIs. Higher plans unlock more APIs by default and raise monthly quotas.

Free

$0 /month

1,000 calls / month
Challenge Generator
Answer Evaluator
Curriculum Mapper
10 req / minute

Growth

$99 /month

50,000 calls / month
All 5 APIs enabled
SPI Compute included
60 req / minute
Priority support

School$499 /month
500,000 calls / month
All 5 APIs + Embed
White-label embed URLs
300 req / minute
Dedicated onboarding

Enterprise

Custom

Unlimited calls
On-premise deploy option
SLA guarantee
Custom curricula
600 req / minute

Get API Access

Submit the form — we provision your spk_ key within one business day and email it to you.

Request received! Your API key will arrive within one business day at the email you provided.

Full name *

Work email *

Organisation *

Organisation type *

Plan interested in

Country

What will you build? *

APIs needed

Challenge Generator Answer Evaluator SPI Compute Simulation Embed Curriculum Mapper