Client Reference

Complete reference for every method on the StudyPlug client. All methods return promises and throw typed errors on failure (see Error Handling).

Constructor

import { StudyPlug } from "studyplug";

const sp = new StudyPlug(options?: StudyPlugOptions);

Option	Type	Default	Description
apiKey	string	—	API key sent as X-StudyPlug-Key header
baseUrl	string	"https://api.studyplug.org"	API base URL
timeout	number	30000	Request timeout in ms
maxRetries	number	2	Automatic retries on 429
fetch	typeof fetch	globalThis.fetch	Custom fetch implementation

---

Health

sp.health()

Check API availability.

const result = await sp.health();
// { status: "ok", timestamp: "2026-02-23T...", uptime: 86400 }

Returns: Promise<{ status: string; timestamp: string; uptime: number }>

---

Catalog: Grades

sp.grades.list()

List all grade levels.

const { data, meta } = await sp.grades.list();
// data.grades: GradeSummary[]

Returns: Promise<ApiResponse<{ grades: GradeSummary[] }>>

sp.grades.get(slug)

Get a grade by slug, including its subjects.

const { data } = await sp.grades.get("grade-3");
// data.grade: GradeDetail (includes grade.subjects)

Param	Type	Description
slug	string	Grade slug (e.g. "kindergarten", "grade-3")

Returns: Promise<ApiResponse<{ grade: GradeDetail }>>

---

Catalog: Subjects

sp.subjects.list()

List all subjects.

const { data } = await sp.subjects.list();
// data.subjects: SubjectSummary[]

Returns: Promise<ApiResponse<{ subjects: SubjectSummary[] }>>

sp.subjects.get(slug)

Get a subject by slug, including its topics.

const { data } = await sp.subjects.get("math");
// data.subject: SubjectDetail (includes subject.topics)

Param	Type	Description
slug	string	Subject slug (e.g. "math", "reading")

Returns: Promise<ApiResponse<{ subject: SubjectDetail }>>

---

Catalog: Topics

sp.topics.list(params?)

List and filter topics with optional pagination.

const { data, pagination } = await sp.topics.list({
  subject: "math",
  grade: "grade-3",
});
// data.topics: TopicSummary[]

Param	Type	Description
subject	string	Filter by subject slug
grade	string	Filter by grade slug
q	string	Full-text search
page	number	Page number (default 1)
pageSize	number	Items per page (default 20)

Returns: Promise<ApiResponse<{ topics: TopicSummary[] }>>

---

Catalog: Skills

sp.skills.list(params?)

Search and filter skills with pagination.

const { data, pagination } = await sp.skills.list({
  grade: "grade-3",
  subject: "math",
  topic: "addition",
  q: "within",
});

Param	Type	Description
grade	string	Filter by grade slug
subject	string	Filter by subject slug
topic	string	Filter by topic slug
q	string	Full-text search
page	number	Page number (default 1)
pageSize	number	Items per page (default 20)

Returns: Promise<ApiResponse<{ skills: SkillSummary[] }>>

sp.skills.get(slug)

Get a skill by slug, including standards and available grades.

const { data } = await sp.skills.get("add-within-10");
// data.skill: SkillSummary
// data.availableGrades: Array<{ slug, name, order }>

Param	Type	Description
slug	string	Skill slug (e.g. "add-within-10")

Returns: Promise<ApiResponse<SkillDetail>>

---

Catalog: Standards

sp.standards.list(params?)

Browse and search educational standards.

const { data, pagination } = await sp.standards.list({
  framework: "CCSS-Math",
  q: "fluently add",
});

Param	Type	Description
framework	string	Filter by framework (e.g. "CCSS-Math", "CCSS-ELA", "NGSS")
grade	number	Filter by grade number
q	string	Full-text search
page	number	Page number (default 1)
pageSize	number	Items per page (default 20)

Returns: Promise<ApiResponse<{ standards: StandardSummary[] }>>

sp.standards.get(code)

Get a standard by code with its mapped skills.

const { data } = await sp.standards.get("3.OA.C.7");
// data.standard: StandardDetail (includes standard.skills)

Param	Type	Description
code	string	Standard code (e.g. "3.OA.C.7")

Returns: Promise<ApiResponse<{ standard: StandardDetail }>>

---

Generate

sp.generate(params)

Generate a batch of content items with an answer key.

const { data, meta } = await sp.generate({
  skill: "add-within-10",
  count: 5,
  seed: 42,
});
// data.items: ContentItem[]
// data.answerKey: AnswerKeyEntry[]

Param	Type	Description
skill	string	Single skill slug
skills	string[]	Multiple skill slugs
standard	string	Single standard code
standards	string[]	Multiple standard codes
grade	string	Grade slug filter
subject	string	Subject slug filter
count	number	Number of items (1-50, default 10)
seed	number	Seed for deterministic output

Provide at least one of skill, skills, standard, or standards.

Returns: Promise<GenerateResponse> ({ data: { items, answerKey }, meta })

sp.generate.single(params)

Generate exactly one content item.

const { data, meta } = await sp.generate.single({
  skill: "add-within-10",
  seed: 42,
});
// data.item: ContentItem
// data.answer: AnswerKeyEntry

Param	Type	Description
skill	string	Skill slug (required)
grade	string	Grade slug filter
seed	number	Seed for deterministic output

Returns: Promise<SingleGenerateResponse> ({ data: { item, answer }, meta })

---

Response Envelope

Every response includes a meta object:

interface ApiMeta {
  requestId: string;
  generatedAt: string;
  seed?: number;
  apiVersion: "v1";
  cacheHit: boolean;
  generationTimeMs?: number;
}

Paginated endpoints also include pagination:

interface Pagination {
  page: number;
  pageSize: number;
  total: number;
  hasNext: boolean;
}