---
title: "Replace the definition"
method: PUT
path: "/quizzes/{id}"
tags: ["Quizzes"]
---

# Replace the definition

`PUT /quizzes/{id}`

## Request

- Base URL: `https://quizgen.dev/api/v1`
- URL: `https://quizgen.dev/api/v1/quizzes/{id}`
- Auth: HTTP bearer

Replaces the definition. Bumps `definition_version`; existing responses keep the version they answered.

## Request body

- QuizDefinition: A quiz/form definition (`schema_version` 1). Generated from the same validator the API enforces; the canonical JSON Schema is also at https://quizgen.dev/schema/v1.json.
  - `schema_version` 1, required
  - `kind` 'quiz' | 'survey' | 'form' | 'email_capture' | 'registration'
  - `title` string, required
  - `description` string
  - `settings` object
    - `collect_respondent` 'none' | 'email_optional' | 'email_required'
    - `autosave` boolean
    - `show_progress` boolean
    - `one_question_per_page` boolean
    - `show_branding` boolean
    - `close_at` string, date-time, nullable
    - `max_responses` integer, nullable
    - `completion` object
      - `message` string
      - `redirect_url` string, uri, nullable
  - `cover` object
    - `title` string
    - `subtitle` string
    - `button_label` string
    - `image_url` string, uri
  - `theme` object
    - `preset` 'warm' | 'midnight' | 'forest' | 'corporate' | 'playful' | 'mono'
    - `accent` string
    - `mode` 'light' | 'dark' | 'auto'
    - `background` string, nullable
    - `font` string, nullable
    - `logo_url` string, uri, nullable
  - `hidden_fields` string[]
  - `sections` object[], required
    - `key` string, required
    - `title` string
    - `blurb` string
    - `one_per_page` boolean
    - `questions` union[], required
      - union
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'short_text', required
          - `prompt` string, required
          - `placeholder` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'long_text', required
          - `prompt` string, required
          - `rows` integer
          - `examples` string[]
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'choice', required
          - `prompt` string, required
          - `options` object[], required
            - `value` string, required
            - `label` string, required
            - `detail` string
            - `image_url` string, uri
          - `follow_up` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'multi_choice', required
          - `prompt` string, required
          - `options` object[], required
            - `value` string, required
            - `label` string, required
            - `detail` string
            - `image_url` string, uri
          - `min` integer
          - `max` integer
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'scale', required
          - `prompt` string, required
          - `min` integer
          - `max` integer
          - `min_label` string
          - `max_label` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'email', required
          - `prompt` string, required
          - `placeholder` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'number', required
          - `prompt` string, required
          - `min` number
          - `max` number
          - `unit` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'date', required
          - `prompt` string, required
          - `min` string
          - `max` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'time', required
          - `prompt` string, required
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'phone', required
          - `prompt` string, required
          - `placeholder` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'url', required
          - `prompt` string, required
          - `placeholder` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'yes_no', required
          - `prompt` string, required
          - `yes_label` string
          - `no_label` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'consent', required
          - `prompt` string, required
          - `terms` object
            - `title` string, required
            - `text` string, required
            - `version` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'signature', required
          - `prompt` string, required
          - `terms` object
            - `title` string, required
            - `text` string, required
            - `version` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'rating', required
          - `prompt` string, required
          - `max` integer
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'slider', required
          - `prompt` string, required
          - `min` number
          - `max` number
          - `step` number
          - `min_label` string
          - `max_label` string
          - `unit` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'payment', required
          - `prompt` string, required
          - `amount_cents` integer
          - `price_options` object[]
            - `value` string, required
            - `label` string, required
            - `amount_cents` integer, required
            - `detail` string
          - `currency` string
          - `button_label` string
        - object
          - `id` string, required
          - `required` boolean
          - `help` string
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'file_upload', required
          - `prompt` string, required
          - `max_files` integer
          - `accept` string[]
        - object
          - `id` string, required
          - `show_if` object
            - `question` string, required
            - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'answered', required
            - `value` union
              - …
          - `type` 'statement', required
          - `title` string, required
          - `body` string[], required
  - `outcomes` object, nullable
    - `method` 'points', required
    - `points` object, required
    - `buckets` object[], required
      - `key` string, required
      - `min` number
      - `max` number
      - `title` string, required
      - `body` string
      - `redirect_url` string, uri, nullable

## Response `200`

Definition replaced.

- CreatedQuiz
  - `id` string, required
  - `slug` string, required
  - `url` string, uri, required
  - `status` string, required
  - `title` string
  - `definition_version` integer
  - `response_count` integer
  - `sandbox` boolean: True when created without a key.
  - `claim_url` string, uri: Sandbox only — the secret link to sign up free and keep the quiz. Give it to your user.

## Other responses

- `401`: Missing or invalid API key.
- `402`: The account is at a plan limit (e.g. live-quiz cap, or a paid-only feature on a free plan). Close/delete a quiz, drop the gated fields, or upgrade.
- `404`: No such quiz (or not yours).
- `422`: The quiz definition failed validation. Fix exactly the fields in `validation_errors` and retry — do not resend an unchanged body.

---

[API](https://skmtc.dev/quizgen/apis/quizgen-api.md) · [All operations](https://skmtc.dev/quizgen/apis/quizgen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/quizgen/apis/quizgen-api/revisions/100cf9a83300?raw)