insert_question
Insert an item at a specific position: a question, a page break (Breaker) or a display block (Statement with content / Swiper with items). Use after / before to reference an existing field code (from get_form's field.code). To insert at the very front: before references the first field's code. To insert at the end, use add_question. Not idempotent: if the call times out it may still have succeeded, so retrying blindly can create a duplicate — check first, then retry only if it is really missing.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | NumberField only: maximum allowed input value (must be >= min). Rejected for other question types. | |
| min | No | NumberField only: minimum allowed input value (respondents cannot submit a smaller number). Rejected for other question types. | |
| code | No | Optional stable identifier for this question (field code). Omit it to let the server auto-generate one. Set a meaningful code (e.g. "q1") when report.formula or a dimension needs to reference this question, so you can write the formula as `{{q1}}` in the same call instead of round-tripping via get_form. Rules: start with a letter or underscore, then only letters/digits/underscores (no hyphens, spaces, or leading digit), at most 64 chars, and not a reserved math word (e, E, pi, PI, tau, phi, i, Infinity, NaN, true, false, null, undefined). Must be unique among all items in the form. | |
| name | No | Question stem text. Allows plain text or restricted HTML (tag allowlist: <p> <strong>/<b> <em>/<i> <u> <s> <mark> <span> <sup> <sub> <br>; other tags are stripped and the text kept). | |
| type | Yes | Question type; Breaker means a page break, no name/choices etc. needed; Statement / Swiper are display-only blocks that collect no answer | |
| unit | No | NumberField only: display unit suffix shown after the input, e.g. "kg" / "$" / "min". Rejected for other question types. | |
| after | No | Insert after this code; choose either after or before | |
| items | No | Swiper only, and required there: the carousel slides in display order, 1-10 of them. Upload the images with prepare_image_upload / finalize_image_upload first and pass the returned media IDs. Rejected for every other type. | |
| score | No | Points this question is worth, default 0 (not scored). Quiz scene: awarded when the answer matches correctAnswer, and a positive value is required once correctAnswer is set. Scored Quiz scene: pairing it with correctAnswer enables the fallback mode above, but choices[i].score is more flexible. Rejected in the outcome_quiz scene, for DateField / TimeField / Rate, and — in the scored_quiz scene — for NumberField (where the submitted number itself is the score) and FillBlank (collected only, never scored). | |
| steps | No | Rate only: number of rating steps, i.e. the highest rating (3-10, default 5). In the scored_quiz scene the submitted rating value (1..steps) is the question score, unless a per-star score is configured in the web app. Rejected for other question types. | |
| words | No | Rate only: optional scale labels evenly distributed under the rating control, e.g. ["Poor", "Excellent"] for the two endpoints (up to 5 labels). Rejected for other question types. | |
| before | No | Insert before this code; choose either after or before | |
| formId | Yes | The form ID to insert the item into | |
| aiMatch | No | Only for FillBlank in the knowledge_quiz scene. Enables AI grading: the AI compares the respondent answer against correctAnswer and scores by accuracy, instead of requiring an exact string match. Requires correctAnswer (the standard answer) and score > 0 (the score earned when accuracy reaches the threshold). Pass an empty object {} to enable with default settings; omit for plain exact-match grading. | |
| choices | No | Choice-based questions only (SingleCheck / MultiCheck / DropDown / Ordering / Cascade), where it is required; ignored for every other type, including TrueFalse — its two options come from trueLabel / falseLabel. Per-type limits: SingleCheck / MultiCheck 2-20 items — for a longer list use DropDown (2-100 items) instead; Ordering 2-10 items; Cascade nests via choices[i].children (up to 3 levels, at most 100 nodes in total). IMPORTANT (knowledge_quiz scene): vary the position of the correct option(s) across questions — do NOT always place the correct answer first. Distribute correct answers roughly evenly over all positions so they are not predictable. | |
| content | No | Statement only, and required there: the text respondents read — an intro, a section lead-in, instructions, a disclaimer. The block renders this and nothing else. Same rich-text rules as `description` (headings / lists / links / <img src> / math formulas). This field also accepts an inline image: put an <img src="..."> in it, where src is a direct image URL that renders in <img src> (a page URL that merely contains an image does not work). Use finalize_image_upload to host an image yourself, or a direct URL the user supplied. Never invent an image URL — omit the image instead of risking a broken one. | |
| explain | No | Optional answer explanation. The frontend renders it in the question's "answer explanation" field (DescriptionEditor); the rich-text rules are identical to description. Do not stuff the answer explanation into description — that is the question's supplementary note and will not be shown as an explanation to respondents/graders. | |
| shuffle | No | Ordering only: shuffle the displayed choice order for each respondent. Defaults to true for MCP-created questions — the stored choices order would otherwise leak the correct order when correctAnswer matches it. Pass false only when the initial order is intentionally meaningful. Rejected for other question types. | |
| multiple | No | DropDown only: allow selecting multiple options (default false = single select). Affects the quiz-scene correctAnswer shape: an array of labels/codes when true, a single one when false. Rejected for other question types (SingleCheck/MultiCheck are inherently single/multi). | |
| required | No | Whether the question is required, default false | |
| precision | No | DateField / TimeField only: picker precision. DateField accepts year | month | day | hour | minute | second (default day; e.g. "month" shows a year-month picker, "second" a full datetime picker). TimeField accepts only minute | second (default minute). Ignored for other question types. | |
| trueLabel | No | TrueFalse only: custom display text for the "true" option (e.g. "Yes" / "Agree"). Ignored for other question types. Leave empty to fall back to the built-in default for the form language ("Correct" in English forms). Does not change the stored answer value, which stays "true". | |
| falseLabel | No | TrueFalse only: custom display text for the "false" option (e.g. "No" / "Disagree"). Ignored for other question types. Leave empty to fall back to the built-in default for the form language ("Incorrect" in English forms). Does not change the stored answer value, which stays "false". | |
| description | No | Optional supplementary note for the question. Allows a wider HTML subset: everything the stem allows + <h1>-<h6> <ul> <ol> <li> <blockquote> <a href> <img src> <hr> <art-field> (variable placeholder, data-type / data-cid); unsafe protocols (javascript:/data:) and unknown attributes are stripped. This field also accepts an inline image: put an <img src="..."> in it, where src is a direct image URL that renders in <img src> (a page URL that merely contains an image does not work). Use finalize_image_upload to host an image yourself, or a direct URL the user supplied. Never invent an image URL — omit the image instead of risking a broken one. | |
| trueOutcomes | No | Outcome scene + TrueFalse only (required there together with falseOutcomes): the outcome codes that answering "true" votes for. Use [] for a side that votes for nothing. Rejected for other question types / scenes. | |
| correctAnswer | No | The "correct answer" of the knowledge_quiz scene; setting it makes the question scored, so pair it with a positive `score`. The shape follows the question type — see the anyOf branches; a choice is referenced by its label or its code, so reference it by code whenever the same label appears more than once (Ordering rejects an ambiguous label outright). Required on SingleCheck / MultiCheck / DropDown / Ordering in the knowledge_quiz scene, optional on FillBlank / NumberField there. NumberField answers must be typeable within min / max and decimalPlaces. Rejected for DateField / TimeField / Rate (data-collection and rating fields; configure date/time scoring in the web app), rejected for FillBlank in the scored_quiz scene (free text is collected only there), and rejected in the outcome_quiz scene (no right or wrong answers there). In the scored_quiz scene prefer choices[i].score per option; passing correctAnswer + score there only falls back to "the matching choice gets score, others get 0". | |
| decimalPlaces | No | NumberField only: how many decimal places respondents may enter (stored as the field's numeric precision), default 0 = integers only. Rejected for other question types. Note this is different from the string `precision` of DateField / TimeField. | |
| falseOutcomes | No | Outcome scene + TrueFalse only (required there together with trueOutcomes): the outcome codes that answering "false" votes for. Use [] for a side that votes for nothing. Rejected for other question types / scenes. | |
| trueDimensionScores | No | scored_quiz scene + TrueFalse only: the points answering "true" adds to each dimension, as a map of dimension code → score (same semantics as choices[i].dimensionScores). Rejected for other question types / scenes. | |
| falseDimensionScores | No | scored_quiz scene + TrueFalse only: the points answering "false" adds to each dimension, as a map of dimension code → score (same semantics as choices[i].dimensionScores). Rejected for other question types / scenes. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | The created question, including its generated code | |
| formId | No | The form that was edited | |
| position | No | 0-based index the question landed at | |
| itemCount | No | Question / page-break count after the insert |