> ## 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.

# Author Forms and Quizzes

> Create, edit, publish, duplicate, and archive native forms through the quiz manage actions.

Authoring follows the same draft-then-publish model as the employer builder: the draft is mutable, every publish snapshots an immutable numbered version, and assignments only ever pin published versions. All actions here require `project_todos:write`.

## `form_create`

<ParamField body="jobId" type="string" required>The job whose organization owns the form.</ParamField>

<ParamField body="title" type="string" required />

<ParamField body="kind" type="string">`FORM` or `QUIZ` — seeds sensible defaults (new forms default to 1 attempt, new quizzes to 2, with a pass rule).</ParamField>
<ParamField body="definition" type="object">Optional complete question definition; omit to start from the kind's default draft.</ParamField>
<ParamField body="settings" type="object">Optional attempt policy, pass rule, and result-release settings.</ParamField>

Creation is receipt-idempotent: retrying the same `idempotencyKey` with the same payload returns the same form; the same key with a different payload returns `409`.

## `form_update_draft`

Replaces the draft definition and settings under an optimistic lock.

<ParamField body="formId" type="string" required />

<ParamField body="expectedRevision" type="number" required>
  The draft revision you last read. A concurrent edit fails with `409` instead of overwriting.
</ParamField>

<ParamField body="title" type="string" required />

<ParamField body="definition" type="object" required />

<ParamField body="settings" type="object" required />

Question types: `SHORT_TEXT`, `PARAGRAPH`, `MULTIPLE_CHOICE`, `CHECKBOXES`, `DROPDOWN`, `LINEAR_SCALE`, `NUMBER`, and `DATE`, plus `SECTION` and `TITLE` layout blocks. A question is auto-graded (answer key plus points), manually graded (points awarded by the employer), or informational — never both auto and manual.

Settings: `attemptPolicy` (`UNLIMITED` or `LIMITED` with `maxAttempts`), an optional `passRule` (percentage or absolute points), and `resultRelease` (`IMMEDIATE` or `MANUAL`).

## `form_publish`

<ParamField body="formId" type="string" required />

<ParamField body="expectedDraftRevision" type="number" required />

Publishes the draft as the next numbered immutable version. Publication validates the definition — for example, a pass rule requires at least one answerable scored question.

## `form_duplicate` and `form_archive`

`form_duplicate` copies a form into a fresh draft. `form_archive` retires the form from new attempts while published versions and response history stay readable.