Resources & Operations¶

Quick reference for every resource — what the handler exposes, which input types it accepts, and which special actions are available. Type names link to the Model Reference.

Assignments¶

client.assignments_handler

An assignment is the pairing of one student with one exercise. It is the central tracking object in Hive: it holds the student's submission history, the current grading status, and which checker (if any) is responsible for grading it. Checkers lock an assignment to claim exclusive grading access, preventing two checkers from working on the same submission simultaneously.

Assignments¶

Method	Description
`search(**filters)`	List assignments; filter by `exercise_id`, `exercise_parent_module_id`, `queue_id`, `user_id_in`, `user_classes_id`, `user_mentor_id`, `user_program_id_in`, `exercise_tags_id_in`
`get(id_)`	Fetch one assignment
`create(AssignmentInput)`	Create an assignment for a user/exercise pair
`update(id_, AssignmentInput)`	Full replace
`patch(id_, AssignmentPatch)`	Partial update
`delete(id_)`	Delete
`lock(id_)`	Claim the assignment as checker (exclusive grading access)
`unlock(id_)`	Release the checker claim
`subscribe(id_)`	Subscribe to update notifications
`unsubscribe(id_)`	Unsubscribe
`get_latest(**filters)`	Latest notification summaries → list of `AssignmentNotification`

Types: Assignment · AssignmentInput · AssignmentPatch

Assignment Responses¶

client.assignments_handler.responses

A response is a single submission event on an assignment — a student submitting files, a checker leaving a grade or comment, or an automated check result. Each response can carry a file attachment. Autochecks (automated grading scripts) run against responses and can be re-triggered manually.

Method	Description
`search(assignment_id)`	List responses for an assignment
`get(assignment_id, response_id)`	Fetch one response
`create(assignment_id, AssignmentResponseInput)`	Add a response
`patch(assignment_id, response_id, AssignmentResponsePatch)`	Partial update
`delete(assignment_id, response_id)`	Delete
`get_files(assignment_id, response_id)`	Download attached file → `FileResponse`
`rerun_autochecks(assignment_id, response_id)`	Trigger autocheck re-evaluation for this response

Types: AssignmentResponse · AssignmentResponseInput · AssignmentResponsePatch

Course¶

client.course_handler

The course handler groups all resources that define the static structure of the curriculum: programs, subjects, modules, exercises, and the form fields attached to exercises. This hierarchy (Program → Subject → Module → Exercise) is the skeleton that assignments and queues are built on top of.

Programs¶

client.course_handler.programs

A program is the top-level container for a course (e.g. "Python Programming"). All subjects, modules, and exercises belong to a program, and student users are enrolled in one.

Full CRUD: search() · get(id_) · create(ProgramInput) · update(id_, ProgramInput) · patch(id_, ProgramPatch) · delete(id_)

Types: Program · ProgramInput · ProgramPatch

Subjects¶

client.course_handler.subjects

A subject is a thematic area within a program (e.g. "Linux", "Control Flow"). It groups related modules and appears as a top-level section in the student's curriculum view.

Method	Description
`search(parent_program_id_in=[…])`	List subjects; optionally filter by program IDs; returns lightweight dicts
`get(id_)`	Fetch one subject → `Subject`
`create(SubjectInput)`	Create
`update(id_, SubjectInput)`	Full replace
`patch(id_, SubjectPatch)`	Partial update
`delete(id_)`	Delete

Types: Subject · SubjectInput · SubjectPatch

Modules¶

client.course_handler.modules

A module is an ordered unit of exercises within a subject (e.g. "Functions", "Unix Basics"). Modules are the building block of queues — a queue item can reference a module to pull in all its exercises.

Full CRUD: search(parent_subject=id) · get(id_) · create(ModuleInput) · update(id_, ModuleInput) · patch(id_, ModulePatch) · delete(id_)

Types: Module · ModuleInput · ModulePatch

Exercises¶

client.course_handler.exercises

An exercise is an individual task or problem that students solve (e.g. a coding challenge, a worksheet). An exercise can carry student starter files, a preview document, and a PATBAS reference solution — a "good" implementation written by staff that the autocheck system uses to validate student submissions.

Method	Description
`search(**filters)`	Filter by `parent_module_id`, `parent_module_parent_subject_id`, `parent_program_id_in`, `queue_id`, `tags_id_in`, `id`
`get(id_)`	Fetch one exercise
`create(ExerciseInput)`	Create
`update(id_, ExerciseInput)`	Full replace
`patch(id_, ExercisePatch)`	Partial update
`delete(id_)`	Delete
`get_preview(id_)`	Download the exercise preview document → `FileResponse`
`get_student_files(id_)`	Download the starter files given to students → `FileResponse`
`get_patbas_files(id_)`	Download the PATBAS reference solution → `FileResponse`
`get_patbas_preview(id_)`	Download the PATBAS preview document → `FileResponse`
`notify_students(id_, AssignmentBulkCommentInput)`	Send a comment to all students currently assigned this exercise

Types: Exercise · ExerciseInput · ExercisePatch · AssignmentBulkCommentInput

Exercise Form Fields¶

client.course_handler.exercises.fields

Form fields are structured input fields attached to an exercise, beyond the student's file upload. They let staff collect specific data per submission — for example a self-assessment score, a free-text reflection, or a multiple-choice question. Fields can be fillable (text, numeric, radio, checkboxes) or unfillable (display-only labels or instructions).

Method	Description
`search(exercise_id)`	List fields
`get(exercise_id, field_id)`	Fetch one
`create(exercise_id, FormFieldInput)`	Create
`update(exercise_id, field_id, FormFieldInput)`	Full replace
`patch(exercise_id, field_id, FormFieldPatch)`	Partial update
`delete(exercise_id, field_id)`	Delete
`duplicate(exercise_id, field_id, FormFieldDuplicationRequest)`	Clone a field
`list_with_top_results(exercise_id)`	List fields with their top student results → list of `FormFieldTopResponse`

Types: FormFieldPatch · FormFieldDuplicationRequest

FormField and FormFieldInput are discriminated unions keyed first on has_value, then on type:

Subtype	`has_value`	`type`	Extra fields
`UnfillableFormField` / `UnfillableFormFieldInput`	`False`	any	—
`TextFormField` / `TextFormFieldInput`	`True`	`"text"`	—
`NumericFormField` / `NumericFormFieldInput`	`True`	`"number"`	`lower_limit: int \| None`, `upper_limit: int \| None`
`RadioFormField` / `RadioFormFieldInput`	`True`	`"multiple"`	`choices: list[str]` (single-select)
`CheckboxesFormField` / `CheckboxesFormFieldInput`	`True`	`"multiResponse"`	`choices: list[str]` (multi-select)

Help¶

client.help_handler

Help threads are student support requests. A student opens a thread when they are stuck; a checker locks it to claim exclusive ownership, then replies. Threads have a category (e.g. error, medical) and a status (open/resolved). Like assignments, threads support subscriptions so staff are notified of updates.

Most help threads have a type "exercise", and are associated with a specific exercise (usually the one the student is working on).

By default, helps are opened by students. Staff can also open help threads, with the special help type "Chat". These are typically not resolved but are used for ongoing staff-student communication, in comment status responses.

Help Threads¶

Method	Description
`search(**filters)`	Filter by `user_id_in`, `exercise_id`, `exercise_parent_module_id`, `exercise_subject_id`, `help_status_in`, `help_type_in`, `created_by`, `current`, `free_text`, `user_mentor_id`, `user_program_id_in`; pass `limit=N` for paginated `ResultsPage`
`get(id_)`	Fetch one
`create(HelpInput)`	Open a help thread
`update(id_, HelpInput)`	Full replace
`patch(id_, HelpInput)`	Partial update
`delete(id_)`	Delete
`lock(id_)`	Checker claims the thread for exclusive response (sets `help.checker`)
`unlock(id_)`	Release checker claim
`subscribe(id_)`	Subscribe to updates
`unsubscribe(id_)`	Unsubscribe
`get_top_responses(id_)`	Fetch top-rated responses → list of `HelpResponse`

Types: Help · HelpInput · HelpPatch

Help Responses¶

client.help_handler.responses

A help response is a single message on a help thread — from either the student or a checker — and may include a file attachment. The bulk_respond method lets a checker post the same reply to many threads at once (e.g. a common clarification).

Method	Description
`search(help_id)`	List responses on a thread
`get(help_id, response_id)`	Fetch one
`create(help_id, HelpResponseInput)`	Add a response
`update(help_id, response_id, HelpResponseInput)`	Full replace
`patch(help_id, response_id, HelpResponsePatch)`	Partial update
`delete(help_id, response_id)`	Delete
`get_files(help_id, response_id)`	Download attached file → `FileResponse`
`get_latest(**filters)`	Latest help-thread activity → list of `HelpLatestItem`
`bulk_respond(HelpResponseInput, **filters)`	Post the same response to many threads at once

Types: HelpResponse · HelpResponseInput · HelpResponsePatch

Management¶

client.management_handler

The management handler covers user accounts, student groups, and physical classroom layout. The register endpoint is the self-service signup path for checkers: a checker receives a registration secret from staff and uses it to create their own account (gaining the Checker clearance in the process). All other user types are created by admins via users.create.

Method	Description
`register(RegistrationRequest)`	Self-register a checker account using a staff-issued secret → `Registration`

Types: RegistrationRequest

Users¶

client.management_handler.users

Users are accounts in the system. There are three clearance levels, each with a different model shape: students (enrolled in a program), checkers (graders), and staff/admins (commanders and system administrators). The check_in action records a daily attendance ping for the authenticated user.

Method	Description
`search()`	List all users
`get(id_)`	Fetch one user
`create(UserInput)`	Create a user
`update(id_, UserInput)`	Full replace
`patch(id_, UserPatch)`	Partial update
`delete(id_)`	Delete
`get_avatar(id_)`	Download profile picture → `FileResponse`
`check_in()`	Record a daily check-in for the current user

UserInput and User are discriminated unions keyed on clearance:

Subtype	`clearance` value	Extra fields
`StudentUserInput` / `StudentUser`	`Hanich`	`program`, `number`, `gender`, `status`
`CheckerUserInput` / `CheckerUser`	`Checker`	`gender`, `status`
`StaffUserInput` / `StaffUser`	`Segel` / `Admin`	`gender`, `status`, `hostname`

Patch type: UserPatch

Current User (Me)¶

client.management_handler.users.me

Convenience endpoints for the authenticated user's own profile — reading it without knowing the user's ID, and updating fields that users are permitted to change themselves.

Method	Description
`get()`	Return the authenticated user's own profile → `StudentCurrentUser` / `CheckerCurrentUser` / `StaffCurrentUser`
`patch(BaseCurrentUserPatch)`	Update own profile fields (e.g. `hostname`)

Types: BaseCurrentUserPatch · StaffCurrentUserPatch · StudentCurrentUserPatch · CheckerCurrentUserPatch

Classes¶

client.management_handler.classes

A class is a group of students enrolled together in a program (e.g. a cohort). The class has an active lesson — which determines which queue each student is currently working from — and supports per-student queue overrides for students who need a different track.

Method	Description
`search()`	List all classes
`get(id_)`	Fetch one
`create(ClassInput)`	Create a class / student group
`update(id_, ClassInput)`	Full replace
`patch(id_, ClassPatch)`	Partial update
`delete(id_)`	Delete
`auto_seat(id_)`	Automatically assign seats for all students in the class
`set_lesson(id_, SetClassLessonRequest)`	Set the class's active lesson (applies lesson rules to assign queues)
`set_queue(id_, SetClassQueueRequest)`	Assign a single queue to all students in the class
`unassign_override_queues(id_)`	Remove any per-student queue overrides, reverting to the class default

Types: Class · ClassInput · ClassPatch · SetClassLessonRequest · SetClassQueueRequest

Seating¶

client.management_handler.seating

Seating records track which student occupies which physical seat in the classroom. They are used to build the room's seat map and can be assigned automatically via classes.auto_seat.

Full CRUD: search() · get(id_) · create(SeatingInput) · update(id_, SeatingInput) · patch(id_, SeatingPatch) · delete(id_)

Types: Seating · SeatingInput · SeatingPatch

Queues¶

client.queues_handler

A queue is an ordered sequence of exercises that students work through. There are two kinds: a ModuleQueue is tied to a taught module and defines the standard exercise sequence for that subject area (e.g. "Python Control Flow — standard track"); a UserQueue is tied to a specific student and defines a personalized sequence (e.g. a remedial plan or an extended challenge track for one learner).

Queues¶

Method	Description
`search(**filters)`	Filter by `class_id`, `mentor_id`, `module`, `module_is_null`, `program_id_in`, `user`, `user_is_null`
`get(id_)`	Fetch one queue
`create(QueueInput)`	Create a queue
`update(id_, QueueInput)`	Full replace
`patch(id_, QueuePatch)`	Partial update
`delete(id_)`	Delete
`duplicate(id_, QueueDuplicationRequest)`	Clone a queue (e.g. to create a variant track)
`delete_new_assignments(queue_id)`	Remove all not-yet-started assignments from a queue

QueueInput and Queue are discriminated unions by the presence of module/user:

Subtype	Key field	Description
`ModuleQueueInput` / `ModuleQueue`	`module`	Standard exercise sequence tied to a module
`UserQueueInput` / `UserQueue`	`user`	Personalized sequence tied to a specific student

create() has typed overloads: passing ModuleQueueInput returns ModuleQueue, passing UserQueueInput returns UserQueue.

Other types: QueuePatch · QueueDuplicationRequest

Queue Items¶

client.queues_handler.items

A queue item is one entry in a queue's ordered list. It can be a direct exercise reference or a nested sub-queue (allowing a queue to embed another queue). The queue_rule on each item controls when a student advances past it — for example, requiring submission before moving on, or waiting for the autocheck to pass.

Method	Description
`search(queue_id)`	List items in a queue
`get(queue_id, item_id)`	Fetch one
`create(queue_id, QueueItemInput)`	Add an item to a queue
`update(queue_id, item_id, QueueItemInput)`	Full replace
`patch(queue_id, item_id, QueueItemPatch)`	Partial update
`delete(queue_id, item_id)`	Remove
`expand(queue_id, item_id)`	Expand a nested sub-queue item in place
`move(queue_id, item_id, QueueItemMoveRequest)`	Reorder item within the queue

QueueItem is a union of two subtypes:

Subtype	Key field	Description
`ExerciseQueueItem`	`exercise: Exercise`	A single exercise entry
`NestedQueueQueueItem`	`nested_queue: Queue`	An embedded sub-queue

QueueItemInput selects what to add:

Input type	Key field	Description
`ModuleQueueItemInput`	`module_id`	Add all exercises from a module (with optional tag filter via `filter_for_tags`)
`ExerciseQueueItemInput`	`exercise_id`	Add a specific exercise
`NestedQueueQueueItemInput`	`nested_queue_id`	Embed another queue

QueueRule values: CHOOSE · WAIT_FOR_SUBMITTED · WAIT_FOR_AUTOCHECKS · WAIT_FOR_DONE

Other types: QueueItemPatch · QueueItemMoveRequest

Schedule¶

client.schedule_handler

The schedule handler manages the timetable and lesson planning side of Hive. Lessons define which queues are assigned to which classes on a given day; calendar events are the actual timetable slots that, when they occur and are linked to a lesson, trigger the lesson's queue assignments.

Lessons¶

client.schedule_handler.lessons

A lesson is a plan that maps classes to queues via a set of rules. When the lesson is applied (either manually via set_lesson or automatically when a linked calendar event occurs), each class and student receives the queue specified by the matching rule. For example: "Beginners class → queue A, except students X and Y who get queue B; Advanced class → queue C."

Full CRUD: search(start, end) · get(id_) · create(LessonInput) · update(id_, LessonInput) · patch(id_, LessonPatch) · delete(id_)

Types: Lesson · LessonInput · LessonPatch

Lesson Rules¶

client.schedule_handler.lessons.rules

A lesson rule is one entry in a lesson's mapping — it specifies which class (or individual student) receives which queue when that lesson is applied.

Full CRUD: search(lesson_id) · get(lesson_id, id_) · create(lesson_id, LessonRuleInput) · update(lesson_id, id_, LessonRuleInput) · patch(lesson_id, id_, LessonRulePatch) · delete(lesson_id, id_)

Types: LessonRule · LessonRuleInput · LessonRulePatch

Calendar Events (read-only)¶

client.schedule_handler.events

Calendar events are the actual timetable slots (e.g. "Tuesday 09:00 – 11:00, room 3"). They are managed externally and exposed here read-only. When an event is linked to a lesson, the lesson's queue assignments are applied to the relevant classes when the event occurs.

Method	Description
`search(start, end, lesson_id)`	List events in a time range
`get(event_id)`	Fetch one event

Types: Event

Event Colors¶

client.schedule_handler.colors

Event colors are named color labels used to visually categorize calendar events in the timetable view (e.g. different colors for different subjects or room types).

Full CRUD: search() · get(id_) · create(EventColorInput) · update(id_, EventColorInput) · patch(id_, EventColorPatch) · delete(id_)

Types: EventColor · EventColorInput · EventColorPatch

Daily Review (create-only)¶

client.schedule_handler.daily_review

The daily review is a special exercise generated at the end of a teaching day. It pulls from the day's calendar events alongside template content to produce a reflection exercise, prompting students to consolidate what they worked on. The API provides a single action to generate this exercise for a given class.

Method	Description
`create(DailyReviewInput)`	Generate a daily-review exercise for a class based on today's events

Types: DailyReviewInput

Tags¶

client.tags_handler

Tags are labels that can be applied to exercises to classify them (e.g. by difficulty, topic, or skill). They are used as filters in exercise searches and in queue items (ModuleQueueItemInput.filter_for_tags) to restrict which exercises from a module are included in a queue.

Full CRUD: search() · get(id_) · create(TagInput) · update(id_, TagInput) · patch(id_, TagPatch) · delete(id_)

Types: Tag · TagInput · TagPatch

Notifications¶

client.notifications_handler

Notifications are system alerts delivered to users when something relevant happens — a new assignment response, a help thread update, etc. Each notification is tied to either an assignment or a help thread and records whether the recipient has read it.

Method	Description
`search(**filters)`	Filter by `assignment`, `assignment_exercise`, `assignment_exercise_in`, `help_id`, `help_in`, `from_user_isnull`, `was_read`
`get(id_)`	Fetch one
`create(NotificationInput)`	Create
`update(id_, NotificationInput)`	Full replace
`patch(id_, NotificationPatch)`	Partial update
`delete(id_)`	Delete

NotificationInput and Notification are discriminated unions by the linked resource:

Subtype	Key field	Description
`ExerciseNotificationInput` / `ExerciseNotification`	`assignment`	Notification tied to a student assignment
`HelpNotificationInput` / `HelpNotification`	`help`	Notification tied to a help thread

Patch type: NotificationPatch

Server Time (read-only)¶

client.time_handler

Returns the server's current datetime, useful for synchronizing time-sensitive client operations (e.g. computing event windows or validating token expiry) against the server clock rather than the client's local time.

Method	Description
`get()`	Return the server's current `datetime`