Skip to content
OpenTrain AIOpenTrain AIOpenTrain AIDocs

Ask OpenTrain

Answers from the documentation, with sources.

What would you like to do with OpenTrain?

AI answers can be mistaken. Check the linked sources. Don’t include private account information.

Open app

DEVELOPER DOCUMENTATION

Author Forms and Quizzes

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

Use with AI
View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in PerplexityAdd to CursorAdd to VS Code
POST/api/public/v1/project-todos/quizzes/manage

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

Section titled “form_create”
jobIdstringbodyrequired
The job whose organization owns the form.
titlestringbodyrequired
kindstringbody
FORM or QUIZ — seeds sensible defaults (new forms default to 1 attempt, new quizzes to 2, with a pass rule).
definitionobjectbody
Optional complete question definition; omit to start from the kind’s default draft.
settingsobjectbody
Optional attempt policy, pass rule, and result-release settings.

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

Section titled “form_update_draft”

Replaces the draft definition and settings under an optimistic lock.

formIdstringbodyrequired
expectedRevisionnumberbodyrequired

The draft revision you last read. A concurrent edit fails with 409 instead of overwriting.

titlestringbodyrequired
definitionobjectbodyrequired
settingsobjectbodyrequired

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

Section titled “form_publish”
formIdstringbodyrequired
expectedDraftRevisionnumberbodyrequired

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

Section titled “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.