Quizzes API

Quizzes are native forms assigned to AI trainers as Project To-dos. Authoring produces immutable published versions; assignments pin exactly one version; results, grading, release, and retakes all live on this surface.

Base path: /api/public/v1/project-todos/quizzes

Endpoints

Method	Path	Purpose
GET	/quizzes/forms?jobId=…	List the organization’s forms available to a job.
GET	/quizzes/forms/{formId}	Read one form: draft, settings, and published versions.
GET	/quizzes/results?jobId=…&formId=…	Attempt results across a form’s published versions.
GET	/quizzes/attempts/{attemptId}	One attempt with every answer.
GET	/quizzes/roster?jobId=…&formId=…	Per-person assignment and attempt status.
GET	/quizzes/export-csv?jobId=…&formId=…	All attempts as spreadsheet-safe CSV.
POST	/quizzes/manage	Discriminated action union for authoring, assigning, grading, release, and retakes.
GET/POST	/quizzes/preview/*	Render one pinned draft or version through the real worker form runner without creating learner state.
GET	/quizzes/coaching-queue?jobId=…	Keyset-paged employer queue for submitted assignments.
GET	/quizzes/coaching/{assignmentId}	Bounded selective-coaching state for one assignment.
GET	/quizzes/coaching/capabilities	Static coaching contract discovery, available before feature enablement.
GET	/quizzes/coaching/export	Bounded masked JSON, JSONL, or formula-neutral CSV export.
GET/POST	/quizzes/worker/coaching/{assignmentId}	Worker-owned coaching context and actions.

Manage actions

Action	Purpose
form_create	Create a draft form or quiz.
form_update_draft	Update the draft (optimistic expectedRevision lock).
form_publish	Publish an immutable numbered version.
form_duplicate / form_archive	Copy into a fresh draft / retire from new attempts.
quiz_todo_preflight	No-write preview of a quiz assignment, including the receipt broad audiences require.
quiz_todo_create	Create and assign the quiz to-do atomically.
grade	Award points for manually graded questions.
release / bulk_release	Make held results visible to the AI trainer(s).
require_retake	Return a submission and grant exactly one extra attempt.
require_retake_plan	No-write validation of a retake batch, emitting ordered per-row commands.
require_retake_apply	Apply exactly the checksum-bound planned retake rows.
coaching_comment / coaching_redo_selection	Draft feedback and the exact question selection.
coaching_thread_resolve / coaching_thread_reopen	Manage feedback-thread state.
coaching_accept	Accept the reviewed submission with a stale-submission guard.
coaching_send_back_plan / coaching_send_back_confirm	Review a no-write selective-return plan, then apply only its signed selection.

Authorization

Employer reads require project_todos:read; employer manage actions require project_todos:write and a claimed account, plus access to the job or form. Worker coaching requires the separate worker-minted project_todos:respond scope and exact assignment ownership; employer keys and employer Full access never include it. Mutating actions require idempotencyKey (8–128 characters of letters, digits, ., _, :, or -).

Answer-key privacy

Expected answers are grading material. Employer-authorized reads of an attempt may include a sanitized expected-answer projection; AI-trainer-facing surfaces never receive answer keys, and worker personal emails never appear in any quiz response.

For selective review cycles, threaded feedback, worker resubmission, exports, and feedback images, see Selective coaching.

For agent-readable desktop/mobile PNGs, ARIA, diagnostics, provenance, and short-lived employer review links, see Hosted quiz visual proof.