Quick Start

This guide walks through the core workflows: browsing the catalog, generating content, and using seeds for deterministic output.

1. Initialize the Client

import { StudyPlug } from "studyplug";

const sp = new StudyPlug();
// or with an API key:
// const sp = new StudyPlug({ apiKey: process.env.STUDYPLUG_API_KEY });

2. Browse the Catalog

The catalog endpoints let you discover grades, subjects, topics, skills, and standards.

// List all grades
const { data } = await sp.grades.list();
console.log(data.grades);
// [{ slug: "kindergarten", name: "Kindergarten", order: 0 }, ...]

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

// List math skills for grade 3
const { data: skillsData, pagination } = await sp.skills.list({
  grade: "grade-3",
  subject: "math",
});
console.log(`Found ${pagination?.total} skills`);

for (const skill of skillsData.skills) {
  console.log(`${skill.slug} — ${skill.name}`);
}

3. Generate Content

The generate function returns a batch of content items with an answer key.

// Generate 5 addition problems
const { data } = await sp.generate({
  skill: "add-within-10",
  count: 5,
});

for (const item of data.items) {
  console.log(item.content); // { type: "arithmetic", operand1: 3, operator: "+", operand2: 5, ... }
}

// Check the answer key
for (const entry of data.answerKey) {
  console.log(`${entry.itemId}: ${entry.answer}`);
}

For a single item, use generate.single:

const { data } = await sp.generate.single({
  skill: "add-within-10",
});

console.log(data.item.content);
console.log(data.answer.answer);

4. Use Seeds for Deterministic Output

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

const first = await sp.generate({ skill: "add-within-10", count: 5, seed: 42 });
const second = await sp.generate({ skill: "add-within-10", count: 5, seed: 42 });

// first.data.items and second.data.items are identical

The seed is also reflected in the response meta:

const { meta } = await sp.generate({ skill: "add-within-10", seed: 42 });
console.log(meta.seed); // 42

5. Look Up Standards

Search standards by framework, grade, or keyword, then generate content aligned to a specific standard.

// Search for a standard
const { data } = await sp.standards.list({ q: "fluently multiply", framework: "CCSS-Math" });
console.log(data.standards[0].code); // "3.OA.C.7"

// Get standard details with mapped skills
const { data: detail } = await sp.standards.get("3.OA.C.7");
for (const skill of detail.standard.skills) {
  console.log(`${skill.slug} (${skill.grade.name})`);
}

// Generate content for a standard
const { data: problems } = await sp.generate({
  standard: "3.OA.C.7",
  count: 10,
});

6. Handle Errors

The SDK throws typed errors you can catch:

import { isNotFoundError, isRateLimitError } from "studyplug";

try {
  await sp.skills.get("nonexistent-skill");
} catch (err) {
  if (isNotFoundError(err)) {
    console.log("Skill not found");
  } else if (isRateLimitError(err)) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else {
    throw err;
  }
}

See Error Handling for the full list of error classes and type guards.

Next Steps

• Client Reference — full API surface documentation
• Examples — copy-paste code for common use cases
• Error Handling — error classes and recovery patterns