Skip to main content
The Hawkings data model is intentionally familiar to anyone who has shipped against Canvas, Moodle, or Google Classroom. Three things make it different:
  1. Courses and cohorts are separated. A Course is the syllabus — the curriculum, the lesson tree, the rubrics. A Cohort is one run of that course for a specific group. Same syllabus, three semesters → one Course, three Cohorts.
  2. Activities and assignments are different. Activities are inline exercises (quizzes, flashcards, short-answer prompts). Assignments are gradable artefacts, with submissions, due dates, and rubrics.
  3. Everything has an AI mode. Anywhere you can author by hand, you can also generate with *.generate*().

​
The graph

Workspace
  ├─ Users
  │   ├─ Students  (role: student)
  │   └─ Teachers  (role: teacher)
  │
  └─ Course (the syllabus)
      └─ Cohort (one run of the course)
          ├─ enrolled Users
          └─ Unit (optional grouping)
              └─ Lesson
                  ├─ LessonContent  (long-form HTML reading)
                  ├─ Activity
                  │   └─ Question
                  └─ Assignment
                      └─ Submission  (per-student attempt)

​
Resources at a glance

​
Workspace
object
A tenant. Holds users and courses. A user can belong to many workspaces (each gets a separate API key).
​
Course
object
The curriculum: name, description, language, target hours, AI instructions. Contains cohorts.A Course has no students by itself. To enroll students, create a Cohort.
​
Cohort
object
A run of a course for a group of students at a moment in time. Carries the actual lessons, students, teachers, assignments, and submissions.Multiple cohorts of the same course are common: spring vs. fall, group A vs. group B, English-track vs. Spanish-track.
​
Unit
object
Optional. Groups lessons inside a cohort. If you don’t need them, ignore them — lessons can hang directly off the cohort.
​
Lesson
object
The atomic learning unit. Has a name, a type, a position, and holds:
  • LessonContent (the long-form reading)
  • Activity (one or many — the inline exercises)
  • Assignment (zero or one — the gradable item)
​
LessonContent
object
HTML reading material. AI-generated, hand-written, or imported from PDF / DOCX / SCORM.
​
Activity
object
One of 22 types: quiz, flashcard, podcast, diagram, glossary, expand, explain… All created with the same activities.create() call.
​
Question
object
A single question inside an Activity. Quizzes have many; flashcards have one (the front/back pair). Each Question can be evaluated individually or as part of the parent Activity.
​
Assignment
object
A gradable task tied to a lesson. Has a rubric, a due date, optional AI evaluator config.
​
Submission
object
A student’s response to an assignment, plus its grade. The grade may be human, AI, or both. AI grading attaches a grading_rationale.
​
User
object
Anyone with access to a workspace. The role field is one of student, teacher, manager, admin. There are sugar resources students and teachers for the common filters.

​
Identifiers

ResourcePrefixExample
Workspacewks_wks_01HX9N5AB3...
Coursecrs_crs_01HX9N5AB3...
Cohortcoh_coh_01HX9N5AB3...
Unituni_uni_01HX9N5AB3...
Lessonlsn_lsn_01HX9N5AB3...
LessonContentlct_lct_01HX9N5AB3...
Activityact_act_01HX9N5AB3...
Questionque_que_01HX9N5AB3...
Assignmentasg_asg_01HX9N5AB3...
Submissionsub_sub_01HX9N5AB3...
Userusr_usr_01HX9N5AB3...
IDs are immutable, URL-safe, and sortable by creation time.

​
Mapping from other LMSs

CanvasMoodleGoogle ClassroomHawkings
AccountSiteDomainWorkspace
CourseCourseCourseCohort
ModuleSection(n/a)Unit
(n/a)Activity(n/a)Lesson
AssignmentAssignmentAssignmentAssignment
SubmissionSubmissionSubmissionSubmission
QuizQuizForm QuizActivity (type: quiz)
A Course (Hawkings) has no direct analogue in those systems — they treat the syllabus and the run as one object. The split is what lets you re-run a course without re-authoring it.