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.

This is the canonical Hawkings workflow. You hand us a brief; we hand you back a course with units, lessons, learning objectives, reading material, and activities. End-to-end it takes ~3 minutes of compute. The code below shows what to call and how to pace it.

​
What you’ll build

By the end of this guide you’ll have:
  • A Course with a generated syllabus.
  • A Cohort with all lessons materialised.
  • AI-generated reading content for each lesson.
  • A mix of activities (quizzes, flashcards, explainers) for each lesson.
  • An assignment with an AI rubric on the final lesson.

​
1. Create the course

import Hawkings from "@hawkings/sdk";

const hk = new Hawkings();

const course = await hk.courses.create({
  name: "Intro to Special Relativity",
  language: "en",
  hours: 12,                          // target total student hours
  description: "An undergraduate intro course covering frames, " +
               "the postulates, time dilation, length contraction, " +
               "and mass-energy equivalence.",
});

console.log(course.id);   // crs_01HX9...
courses.create() returns immediately. The course is status: "draft" until you generate or attach a syllabus.

​
2. Generate the syllabus

await hk.courses.generateSyllabus(course.id, {
  brief: course.description!,
  audience: "third-year physics undergrads",
  hours: 12,
  // Optional: pin a research artefact to ground the generation
  // research_id: "res_..."
});
Wait for it to finish: 
const ready = await hk.poll(
  () => hk.courses.retrieve(course.id, { expand: ["cohorts.lessons"] }),
  { until: c => c.status === "ready", interval_ms: 2000 },
);

console.log(ready.cohorts[0].lessons.map(l => l.name));
// [
//   "Reference frames and Galilean relativity",
//   "The postulates of special relativity",
//   "Time dilation",
//   "Length contraction",
//   ...
// ]
A default Cohort was created automatically. Lessons live on the cohort, not on the course — see Courses vs. Cohorts.

​
3. Generate reading content

For each lesson, ask the AI to write a long-form HTML reading: 
const cohort = ready.cohorts[0];

await Promise.all(
  cohort.lessons.map(lesson =>
    hk.lessonContents.generate({ lesson_id: lesson.id }),
  ),
);

await hk.poll(
  () => hk.cohorts.lessonStatuses(cohort.id),
  { until: rows => rows.every(r => r.content_status === "ready") },
);
If you’d rather generate everything at once instead of per-lesson: 
await hk.lessonContents.generate({ cohort_id: cohort.id });
That’s a single call, fans out internally, and is what we recommend in production.

​
4. Generate activities

await hk.activities.generate({
  cohort_id: cohort.id,
  count: 5,
  types: ["explain", "quiz", "flashcard"],
});

await hk.poll(
  () => hk.cohorts.lessonStatuses(cohort.id),
  { until: rows => rows.every(r => r.activities_status === "ready") },
);
Now every lesson has 5 activities.

​
5. Add an assignment to the final lesson

const lessons = (await hk.lessons.list({ cohort_id: cohort.id })).data;
const finalLesson = lessons.at(-1)!;

await hk.assignments.create({
  lesson_id: finalLesson.id,
  type: "essay",
  title: "Explain mass-energy equivalence in your own words",
  rubric: {
    criteria: [
      { name: "clarity", weight: 0.4 },
      { name: "physics accuracy", weight: 0.4 },
      { name: "use of sources", weight: 0.2 },
    ],
    scale: { min: 0, max: 10 },
  },
});

​
6. Verify

const final = await hk.courses.retrieve(course.id, {
  expand: [
    "cohorts.lessons.activities",
    "cohorts.lessons.content",
    "cohorts.lessons.assignment",
  ],
});

for (const lesson of final.cohorts[0].lessons) {
  console.log(lesson.name);
  console.log(`  content: ${lesson.content?.id ?? "—"}`);
  console.log(`  activities: ${lesson.activities.length}`);
  console.log(`  assignment: ${lesson.assignment?.title ?? "—"}`);
}
You’re done. Enrol students with cohorts.create({ student_emails }), or export to SCORM for an external LMS.

​
Same thing, in one go

For prototypes and demos: 
const course = await hk.courses.create({
  name: "Intro to Special Relativity",
  language: "en",
  hours: 12,
});

await hk.courses.generateSyllabus(course.id, { brief: "...", hours: 12 });

const cohort = (await hk.courses.retrieve(course.id, { expand: ["cohorts"] }))
  .cohorts[0];

await hk.lessonContents.generate({ cohort_id: cohort.id });
await hk.activities.generate({ cohort_id: cohort.id, count: 5 });

await hk.poll(
  () => hk.cohorts.lessonStatuses(cohort.id),
  { until: rows => rows.every(r => r.content_status === "ready" && r.activities_status === "ready") },
);

​
Cost & runtime

Roughly: a 12-hour course → ~10 lessons → ~$2.50 in AI costs and ~3 minutes wall-clock on shared infrastructure. See your dashboard for exact unit prices.

​
What’s next

Build an AI tutor

Add a per-lesson tutor chat.

Export to SCORM

Hand the course to any LMS.

Sync students from your LMS

Bring your existing roster.

Grade an open-ended answer

Wire AI grading + human review.