Content Items

Overview

Every piece of educational content the StudyPlug API produces is a ContentItem. Whether it is an arithmetic problem, a reading comprehension passage, or a word search puzzle, the shape is always the same top-level structure. Your application decides how to render it — as a worksheet, quiz, flashcard, or interactive widget.

ContentItem Structure

{
  "id": "ci_a1b2c3d4",
  "type": "arithmetic",
  "skill": "add-within-10",
  "gradeLevel": 1,
  "standard": {
    "code": "1.OA.C.6",
    "framework": "CCSS-Math",
    "description": "Add and subtract within 20."
  },
  "difficulty": {
    "level": "easy",
    "dok": 1,
    "bloom": "remember",
    "gradeEquivalent": 1.0,
    "complexityScore": 15
  },
  "content": { ... },
  "answer": { ... },
  "renderHints": { ... }
}

Field Reference

Field	Type	Description
id	string	Unique identifier for this item.
type	string	One of 18 content types. Determines the shape of content.
skill	string	Skill slug the item was generated for (e.g., "add-within-10").
gradeLevel	integer	Grade level as an integer, 0—8. 0 represents Kindergarten.
standard	object	Standards alignment with code, framework, and description.
difficulty	object	Difficulty metadata including Bloom’s taxonomy and DOK level.
content	object	The polymorphic content body. Shape depends on type.
answer	object	Answer descriptor with the correct value, display form, and explanation.
renderHints	object	Optional hints for print, digital, and visual rendering.

The Polymorphic content Field

The content field is a discriminated union keyed on type. The type field at the top level of the ContentItem always matches the type field inside content. This means you can switch on type to determine the shape:

switch (item.type) {
  case "arithmetic":
    // item.content has operand1, operand2, operator
    break;
  case "multiple-choice":
    // item.content has stem, choices, correctIndex
    break;
  case "passage-based":
    // item.content has passage, questionCount
    break;
  // ... and so on for all 18 types
}

See Content Types for the full schema of each type.

The answer Descriptor

Every ContentItem includes a structured answer so consumers can build self-checking experiences:

{
  "type": "exact",
  "value": 7,
  "display": "7",
  "explanation": "3 + 4 = 7",
  "acceptableAnswers": ["7", "seven"]
}

Answer Type	When Used
exact	Arithmetic, fill-in-the-blank, short answer with a single correct value.
multiple-choice-index	Multiple-choice items. value is the zero-based index.
boolean	True/false items. value is true or false.
set	Matching and ordering items where the answer is a collection.
open-ended	Short-answer items without a single correct answer.

Difficulty Metadata

The difficulty object provides multiple lenses on item complexity:

• level — easy, medium, or hard. A simple three-tier classification.
• dok — Webb’s Depth of Knowledge, 1—4. Most generated items are DOK 1 (recall) or DOK 2 (skill/concept).
• bloom — Bloom’s Taxonomy level: remember, understand, apply, analyze, evaluate, or create.
• gradeEquivalent — Decimal grade level (e.g., 3.5 means mid-Grade-3 difficulty).
• complexityScore — A 0—100 composite score combining all factors.

Render Hints

The optional renderHints object suggests how to present the item without dictating layout. The API returns structured data, not HTML — your renderer makes the final decisions.

{
  "print": {
    "suggestedWidth": "half-page",
    "orientation": "portrait",
    "showWorkSpace": true,
    "columns": 2
  },
  "digital": {
    "interactiveType": "input",
    "inputType": "number"
  },
  "visuals": {
    "diagramSvg": "<svg>...</svg>",
    "imageRefs": [
      { "id": "img_apple", "alt": "A red apple", "category": "object" }
    ]
  }
}

Tip

Render hints are suggestions, not requirements. A quiz app can ignore print hints entirely, and a worksheet renderer can ignore digital hints. Use what fits your medium.

Consuming ContentItems

The same ContentItem can power multiple experiences:

Medium	What You Use
Worksheet	content for the problem layout, answer for the answer key, renderHints.print for page formatting.
Interactive Quiz	content for the question, answer for validation, renderHints.digital for input type.
Flashcard	content for the front (question), answer.display for the back.
API Consumer / AI Agent	The full JSON object. Agents can read standard, difficulty, and content to reason about the item.

Next Steps

• Content Types — Full schema for each of the 18 content body types.
• Skills & Standards — How skills map to the curriculum hierarchy and standards frameworks.
• Deterministic Generation — How seeds make output reproducible.