> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quizzes API

> HTTP reference for authoring native forms and quizzes, assigning published versions as Project To-dos, and reading results.

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.

```text theme={null}
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.