Generate a single content item

POST

/api/v1/generate/single

• Local development
• Production

Generate exactly one content item for a specific skill.

Request Body ^required

object

skill

required

Skill slug to generate for

string

grade

Grade slug filter

string

seed

Seed for deterministic generation

integer

Responses

200

Single generated content item

object

data

object

item

Universal content item — the type field determines the shape of content.

object

id

required

string

type

required

string

Allowed values: arithmetic multiple-choice fill-blank true-false short-answer passage-based matching ordering diagram word-puzzle picture-counting data-table

skill

required

Skill slug this item was generated for

string

gradeLevel

required

Grade order (0=K, 1-8)

integer

<= 8

standard

object

code

string

Example

3.OA.C.7

framework

string

Example

CCSS-MATH

description

string

difficulty

required

object

level

required

string

Allowed values: easy medium hard

dok

Depth of Knowledge level

integer

>= 1 <= 4

bloom

Bloom’s taxonomy level

string

Allowed values: remember understand apply analyze evaluate create

gradeEquivalent

Grade-equivalent difficulty

number

complexityScore

Normalized complexity score (0-100)

number

<= 100

content

required

One of: discriminator: type

object

object

type

required

string

Allowed value: arithmetic

operand1

required

One of:

number

number

object

object

numerator

required

integer

denominator

required

integer

> 0

wholeNumber

integer

display

required

string

Example

3/4

operand2

required

One of:

number

number

object

object

numerator

required

integer

denominator

required

integer

> 0

wholeNumber

integer

display

required

string

Example

3/4

operand3

number

operator

required

string

Allowed values: + - × ÷

displayFormat

string

Allowed values: horizontal vertical

missingOperand

string

Allowed values: operand1 operand2 result

object

object

type

required

string

Allowed value: multiple-choice

stem

required

The question text

string

choices

required

Array<object>

object

text

required

string

isDistractor

required

boolean

distractorReason

string

correctIndex

required

integer

explanation

string

object

object

type

required

string

Allowed value: fill-blank

template

required

Text with blank indicated by ___

string

Example

The capital of France is ___.

answer

required

string

acceptableAnswers

Array<string>

caseSensitive

boolean

object

object

type

required

string

Allowed value: true-false

statement

required

string

isTrue

required

boolean

explanation

string

object

object

type

required

string

Allowed value: short-answer

question

required

string

sampleAnswer

string

keywords

Array<string>

object

object

type

required

string

Allowed value: passage-based

passage

required

object

text

required

string

title

required

string

genre

required

string

Allowed values: fiction nonfiction poetry

wordCount

required

integer

readingLevel

string

paragraphs

required

Array<string>

questionCount

required

integer

object

object

type

required

string

Allowed value: matching

instructions

required

string

pairs

required

Array<object>

object

left

required

string

right

required

string

shuffledRight

required

The ‘right’ values in shuffled order for the student

Array<string>

object

object

type

required

string

Allowed value: ordering

instructions

required

string

items

required

Items in correct order

Array<string>

shuffledItems

required

Items in shuffled order for the student

Array<string>

object

object

type

required

string

Allowed value: diagram

diagramKind

required

string

Allowed values: number-line shape coordinate-plane bar-model clock ruler

diagramData

required

Diagram-specific structured data

object

key

additional properties

any

question

required

string

answer

required

One of:

string

string

number

number

object

object

type

required

string

Allowed value: word-puzzle

puzzleType

required

string

Allowed values: word-search crossword

grid

required

2D character grid

Array<Array<string>>

words

required

Array<object>

object

word

required

string

clue

string

gridSize

required

object

rows

required

integer

cols

required

integer

object

object

type

required

string

Allowed value: picture-counting

count

required

integer

> 0

objectDescription

required

What to count (e.g. ‘apples’, ‘stars’)

string

object

object

type

required

string

Allowed value: data-table

tableTitle

required

string

headers

required

Array<string>

rows

required

Array<Array<string>>

question

required

string

answer

required

string

answer

required

object

type

required

string

Allowed values: exact multiple-choice-index open-ended set boolean

value

required

One of:

string

string

number

number

boolean

boolean

display

required

Human-readable display of the answer

string

unit

Unit of measurement if applicable

string

explanation

Explanation of why this is the answer

string

acceptableAnswers

Alternative acceptable answers

Array<string>

renderHints

Optional presentation hints for consumers rendering the content.

object

print

object

suggestedWidth

string

Allowed values: quarter-page half-page full-page

orientation

string

Allowed values: portrait landscape

showWorkSpace

boolean

columns

integer

digital

object

interactiveType

string

Allowed values: input drag-drop tap-choice draw

inputType

string

Allowed values: number text fraction

visuals

object

diagramSvg

SVG markup for diagrams

string

imageRefs

Array<object>

object

id

string

alt

string

category

string

Allowed values: object diagram symbol

answer

object

itemId

required

string

answer

required

Human-readable answer display

string

meta

object

requestId

string format: uuid

generatedAt

string format: date-time

apiVersion

string

Allowed values: v1

cacheHit

boolean

seed

integer

400

Invalid JSON

RFC 7807 Problem Details

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string

retryAfter

Seconds to wait before retrying (present on 429 responses)

integer

404

Skill not found

RFC 7807 Problem Details

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string

retryAfter

Seconds to wait before retrying (present on 429 responses)

integer

422

Missing skill field

RFC 7807 Problem Details

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string

retryAfter

Seconds to wait before retrying (present on 429 responses)

integer

429

Rate limit exceeded

RFC 7807 Problem Details

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string

retryAfter

Seconds to wait before retrying (present on 429 responses)

integer

Example

{
  "type": "https://api.studyplug.org/errors/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 20 requests per minute. Please wait before retrying.",
  "instance": "/api/v1/skills",
  "retryAfter": 12
}

Headers

Retry-After

integer

Seconds until rate limit resets

X-RateLimit-Limit

integer

Max requests per window

X-RateLimit-Remaining

integer

Allowed values: 0

Always 0 when rate limited