Skip to main content
POST
/
v1
/
courses
/
{id}
/
syllabus
/
generate
Generate a syllabus
curl --request POST \
  --url https://api.example.com/v1/courses/{id}/syllabus/generate \
  --header 'Content-Type: application/json' \
  --data '
{
  "brief": "<string>",
  "audience": "<string>",
  "hours": 123,
  "research_id": "<string>"
}
'

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.

​
Path parameters

​
id
string
required

​
Body

​
brief
string
required
A short description of what the course should cover. Two paragraphs is plenty; one is fine.
​
audience
string
Free-text learner profile. E.g. "third-year physics undergrads".
​
hours
integer
Override the course’s hours. Affects how granular the lesson split is.
​
research_id
string
Ground the syllabus in a Research artefact.

​
Behaviour

This call is async. The course transitions to status: "pending" and then to "ready" (or "error"). You can poll or subscribe to the course.syllabus_generated webhook.

​
Examples

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" },
);

​
Returns

The course in status: "pending". 
{
  "id": "crs_123",
  "status": "pending",
  "estimated_ready_at": "2026-05-10T12:01:30Z"
}