Quickstart

The StudyPlug API generates educational content items for K-5 students on demand (K-8 planned). This guide walks you through your first API call, browsing the curriculum catalog, and using seeds for reproducible output.

Your First Request

Generate addition problems with a single request. No API key required.

Paste this in your browser — you’ll see JSON data immediately:

https://api.studyplug.org/api/v1/problems?skill=add-within-10&grade=kindergarten&count=5&seed=42

The GET /problems endpoint is the easiest way to start. Query parameters are simpler than JSON bodies, the URL is shareable, and adding seed makes the response deterministic and cacheable.

# Paste in browser or curl — no headers needed
curl "https://api.studyplug.org/api/v1/problems?skill=add-within-10&grade=kindergarten&count=5&seed=42"

# Single item
curl "https://api.studyplug.org/api/v1/problems/single?skill=multiply-by-3&grade=grade-3&seed=42"

# Multiple skills (comma-separated)
curl "https://api.studyplug.org/api/v1/problems?skills=add-within-10,subtract-within-10&grade=kindergarten&count=6"

# By standard code
curl "https://api.studyplug.org/api/v1/problems?standard=3.OA.C.7&count=5&seed=100"

# POST for batch generation with full control
curl -X POST https://api.studyplug.org/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"skill": "add-within-10", "grade": "kindergarten", "count": 5}'

npm install studyplug

import { StudyPlug } from "studyplug";

const sp = new StudyPlug();
const { data } = await sp.generate({
  skill: "add-within-10",
  grade: "kindergarten",
  count: 5,
});

console.log(data.items);     // 5 arithmetic ContentItems
console.log(data.answerKey); // answers with explanations

The response includes a data object with items (the generated content) and answerKey (the answers), plus a meta object with request metadata.

Browse the Catalog

The API organizes content into a hierarchy: grades contain subjects, which contain topics, which contain skills. Use the catalog endpoints to discover what is available.

curl
TypeScript SDK

# List all grades
curl https://api.studyplug.org/api/v1/grades

# Get a grade with its subjects
curl https://api.studyplug.org/api/v1/grades/grade-3

# List skills filtered by grade and subject
curl "https://api.studyplug.org/api/v1/skills?grade=grade-3&subject=math"

# Search skills by keyword
curl "https://api.studyplug.org/api/v1/skills?q=fraction"

// List all grades
const { data: gradesData } = await sp.grades.list();
console.log(gradesData.grades);

// Get a specific grade with its subjects
const { data: gradeData } = await sp.grades.get("grade-3");
console.log(gradeData.grade.subjects);

// Search skills by grade and subject
const { data: skillsData } = await sp.skills.list({
  grade: "grade-3",
  subject: "math",
});
console.log(skillsData.skills);

// Search skills by keyword
const { data: searchData } = await sp.skills.list({ q: "fraction" });
console.log(searchData.skills);

Generate Content by Skill

Once you find a skill slug from the catalog, pass it to the problems or generate endpoint. You can request a batch of items or a single item.

# Batch: 10 items (default)
curl "https://api.studyplug.org/api/v1/problems?skill=multiply-by-6"

# Single item
curl "https://api.studyplug.org/api/v1/problems/single?skill=multiply-by-6"

# With seed for deterministic, cacheable output
curl "https://api.studyplug.org/api/v1/problems?skill=multiply-by-6&count=5&seed=42"

# Batch: 10 items (default)
curl -X POST https://api.studyplug.org/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"skill": "multiply-by-6"}'

# Single item
curl -X POST https://api.studyplug.org/api/v1/generate/single \
  -H "Content-Type: application/json" \
  -d '{"skill": "multiply-by-6"}'

// Batch: 10 items (default)
const batch = await sp.generate({ skill: "multiply-by-6" });

// Single item
const single = await sp.generate.single({ skill: "multiply-by-6" });
console.log(single.data.item);   // one ContentItem
console.log(single.data.answer); // its answer

Deterministic Output with Seeds

Pass a seed parameter to get the exact same content every time. This is useful for caching, testing, and sharing reproducible worksheets.

# Same seed = same output, every time. Paste in browser to verify!
curl "https://api.studyplug.org/api/v1/problems?skill=add-within-10&count=5&seed=42"

Seeded GET requests return Cache-Control: public, s-maxage=86400 — CDNs cache them automatically.

curl -X POST https://api.studyplug.org/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"skill": "add-within-10", "count": 5, "seed": 42}'

const result = await sp.generate({
  skill: "add-within-10",
  count: 5,
  seed: 42,
});
// Run this again with seed: 42 and you get identical items

Seeded requests are cached server-side, so repeated calls with the same parameters return instantly.

Next Steps

Authentication — learn about API keys and rate limits
Rate Limits — understand throttling and retry behavior
Content Items — the universal ContentItem data model
API Reference — full endpoint documentation
SDK Reference — TypeScript SDK setup and usage