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 5 addition problems with a single request. No API key required.

curl

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

TypeScript SDK

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

# 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"

TypeScript SDK

// 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 generate endpoint. You can request a batch of items or a single item.

curl

# 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"}'

TypeScript SDK

// 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.

curl

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

TypeScript SDK

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 also 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