Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hawkings.education/llms.txt

Use this file to discover all available pages before exploring further.

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).
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…?”
podcast — generated audio walkthrough of the lesson. diagram — generated diagram (mermaid / plain image).
regulation — self-regulation prompts (“rate your confidence”, “pick the next topic”).

​
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",
});
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
});
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? ... }]
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 });
Both forms return a Submission, so the same downstream code handles in-lesson quizzes and graded assignments.

​
When to use each type — heuristics

You wantReach for
A check-for-understanding after a 3-minute readingquiz (1-3 true_false items)
A drill on terminologyflashcard
A reflection promptregulation
A test of writingshort_answer
A 5-minute audio recappodcast
Conceptual exploration without a “right” answerdiscover or application
Sources for further readingbibliography