> ## 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.

# Activities & Questions

> The 22 activity types, when to use each, and how questions work.

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

<AccordionGroup>
  <Accordion title="Reading aids" defaultOpen>
    `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).
  </Accordion>

  <Accordion title="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…?"
  </Accordion>

  <Accordion title="Multimedia">
    `podcast` — generated audio walkthrough of the lesson.
    `diagram` — generated diagram (mermaid / plain image).
  </Accordion>

  <Accordion title="Meta">
    `regulation` — self-regulation prompts ("rate your confidence", "pick the next topic").
  </Accordion>
</AccordionGroup>

## Creating an activity

One method, regardless of type:

<CodeGroup>
  ```ts TypeScript theme={null}
  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",
  });
  ```

  ```php PHP theme={null}
  $hk->activities->create([
      'lesson_id' => 'lsn_123',
      'type' => 'quiz',
      'variant' => 'true_false',
      'prompt' => 'Generate 5 questions covering the postulates of special relativity.',
      'difficulty' => 'intermediate',
  ]);
  ```
</CodeGroup>

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":

<CodeGroup>
  ```ts TypeScript theme={null}
  await hk.activities.generate({
    lesson_id: "lsn_123",
    count: 5,
    types: ["explain", "quiz", "flashcard"],   // optional weighting
  });
  ```

  ```php PHP theme={null}
  $hk->activities->generate([
      'lesson_id' => 'lsn_123',
      'count' => 5,
      'types' => ['explain', 'quiz', 'flashcard'],   // optional weighting
  ]);
  ```
</CodeGroup>

This returns an async handle. Poll or webhook-listen for completion;
see [AI generation](/concepts/ai-generation).

## Questions

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

<CodeGroup>
  ```ts TypeScript theme={null}
  const a = await hk.activities.retrieve("act_123", { expand: ["questions"] });
  // a.questions: [{ id, type, prompt, choices, correct_answer? ... }]
  ```

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

Evaluate one or all of them:

<CodeGroup>
  ```ts TypeScript theme={null}
  // 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 });
  ```

  ```php PHP theme={null}
  // 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]);
  ```
</CodeGroup>

Both forms return a [`Submission`](/concepts/assignments-and-submissions),
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`                  |