Quizzes API - OpenTrain AI

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.

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.

Authorization

Reads require project_todos:read; manage requires project_todos:write and a claimed account, plus employer access to the job or form. 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.

⌘I