Activities & Questions

An Activity is anything you put inside a lesson that the learner does. A Question is a single prompt inside a quiz-like activity. In other LMSs you’d find these scattered across “quiz”, “discussion”, “assignment”, “page”. In Hawkings they’re one resource with a type field.

The 22 types

Reading aids

introduction — a one-paragraph hook for the lesson. objective — explicit learning goals. expand — deeper-dive on a sub-topic. explain — a focused explanation of a concept. explain_simple — same, ELI5-style. audio_resume / text_resume — short summaries, audio or text. glossary — defined terms. bibliography — sources and further reading. underline — key passages highlighted in source text. remember — flashcard-style recall prompts (single concept).

Interactive

quiz — multi-question quiz. Has variants:

true_false
fill_blank
matching
grouping
element_order
open_ended
mixed (combines variants)

flashcard — front/back card deck. short_answer — single open-ended question, AI-graded. practical — hands-on exercise. integrative — combines concepts from multiple lessons. application — apply the concept to a real-world scenario. discover — exploratory prompt: “given X, what would happen if…?”

Multimedia

podcast — generated audio walkthrough of the lesson. diagram — generated diagram (mermaid / plain image).

Creating an activity

One method, regardless of type:

await hk.activities.create({
  lesson_id: "lsn_123",
  type: "quiz",
  variant: "true_false",
  prompt: "Generate 5 questions covering the postulates of special relativity.",
  difficulty: "intermediate",
});

$hk->activities->create([
    'lesson_id' => 'lsn_123',
    'type' => 'quiz',
    'variant' => 'true_false',
    'prompt' => 'Generate 5 questions covering the postulates of special relativity.',
    'difficulty' => 'intermediate',
]);

The SDK only requires lessonId and type. Everything else has sensible defaults — including prompt, which the SDK will derive from the lesson context if you don’t supply one.

Generating in bulk

Most authoring flows want “give me a sensible mix of activities for this lesson”:

await hk.activities.generate({
  lesson_id: "lsn_123",
  count: 5,
  types: ["explain", "quiz", "flashcard"],   // optional weighting
});

$hk->activities->generate([
    'lesson_id' => 'lsn_123',
    'count' => 5,
    'types' => ['explain', 'quiz', 'flashcard'],   // optional weighting
]);

This returns an async handle. Poll or webhook-listen for completion; see AI generation.

Questions

Every quiz-like activity has one or more Questions. Read them with expand:

const a = await hk.activities.retrieve("act_123", { expand: ["questions"] });
// a.questions: [{ id, type, prompt, choices, correct_answer? ... }]

$a = $hk->activities->retrieve('act_123', ['expand' => ['questions']]);
// $a->questions: [{ id, type, prompt, choices, correct_answer? ... }]

Evaluate one or all of them:

// All at once
await hk.activities.evaluate("act_123", {
  answers: [
    { question_id: "que_1", value: true },
    { question_id: "que_2", value: "c" },
  ],
});

// One question
await hk.questions.evaluate("act_123", "que_1", { answer: true });

// All at once
$hk->activities->evaluate('act_123', [
    'answers' => [
        ['question_id' => 'que_1', 'value' => true],
        ['question_id' => 'que_2', 'value' => 'c'],
    ],
]);

// One question
$hk->questions->evaluate('act_123', 'que_1', ['answer' => true]);

Both forms return a Submission, so the same downstream code handles in-lesson quizzes and graded assignments.

When to use each type — heuristics

You want	Reach for
A check-for-understanding after a 3-minute reading	`quiz` (1-3 `true_false` items)
A drill on terminology	`flashcard`
A reflection prompt	`regulation`
A test of writing	`short_answer`
A 5-minute audio recap	`podcast`
Conceptual exploration without a “right” answer	`discover` or `application`
Sources for further reading	`bibliography`

Get started

Core concepts

Guides

Activities & Questions

The 22 types

Creating an activity

Generating in bulk

Questions

When to use each type — heuristics

​The 22 types

​Creating an activity

​Generating in bulk

​Questions

​When to use each type — heuristics

The 22 types

Creating an activity

Generating in bulk

Questions

When to use each type — heuristics