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

# Generate a syllabus

> Generate a unit/lesson tree with learning objectives. Async.

## Path parameters

<ParamField path="id" type="string" required />

## Body

<ParamField body="brief" type="string" required>
  A short description of what the course should cover. Two paragraphs
  is plenty; one is fine.
</ParamField>

<ParamField body="audience" type="string">
  Free-text learner profile. E.g. `"third-year physics undergrads"`.
</ParamField>

<ParamField body="hours" type="integer">
  Override the course's `hours`. Affects how granular the lesson split is.
</ParamField>

<ParamField body="research_id" type="string">
  Ground the syllabus in a [Research](/api-reference/overview) artefact.
</ParamField>

## Behaviour

This call is async. The course transitions to `status: "pending"` and
then to `"ready"` (or `"error"`). You can [poll](/concepts/ai-generation#polling)
or subscribe to the `course.syllabus_generated` webhook.

## Examples

<CodeGroup>
  ```ts TypeScript theme={null}
  await hk.courses.generateSyllabus("crs_123", {
    brief: "An undergraduate intro to special relativity, ending with mass-energy equivalence.",
    audience: "third-year physics undergrads",
    hours: 12,
  });

  const ready = await hk.poll(
    () => hk.courses.retrieve("crs_123", { expand: ["cohorts.lessons"] }),
    { until: c => c.status === "ready" },
  );
  ```

  ```php PHP theme={null}
  $hk->courses->generateSyllabus('crs_123', [
      'brief' => 'An undergraduate intro to special relativity, ending with mass-energy equivalence.',
      'audience' => 'third-year physics undergrads',
      'hours' => 12,
  ]);

  $ready = $hk->poll(
      fn () => $hk->courses->retrieve('crs_123', ['expand' => ['cohorts.lessons']]),
      ['until' => fn ($c) => $c->status === 'ready'],
  );
  ```
</CodeGroup>

## Returns

The course in `status: "pending"`.

```json theme={null}
{
  "id": "crs_123",
  "status": "pending",
  "estimated_ready_at": "2026-05-10T12:01:30Z"
}
```