Skip to main content
POST
Creates and/or updates questions in a single study in one request. Items with an id are updated; items without an id are created (appended after the existing questions in the order given). Returns 201.
string
Optional, up to 255 characters. Makes the request safe to retry; see Retries.
object[]
required
The questions to create or update, at most 500 per request (more returns 422). Every item must include the same study_id. Recognized fields per item:
  • id — include to update an existing question; omit to create.
  • study_id — required on every item.
  • content — question text; may include {{Q:...}} references.
  • type — question type (see List questions for values).
  • props — type-specific settings object. On updates it is merged with the existing props, with the same handling of multiple-choice exclusiveOptions as Update question and the same validation of earlierAnswerChecks (checks against earlier answers).
  • interviewer_notes — private AI guidance.
  • display_condition_match — all or any, as in Update question; any other value returns 400.
  • assets — media assets array.
  • asset — attach a verified upload ({ "upload_id", "layout", "sizing", "max_width_percent", "autoplay", "loop" }) or copy another question’s media in the same study ({ "copy_from_question_id", "layout" }), see Update question; null removes the default-language asset (translated-language variants are kept). Cannot be combined with assets, embedded_website_url, or figma_prototype_url on the same item.
  • embedded_website_url — an https:// page framed beside the question; not on websiteTest, prototypeTask, or calendar. Figma links are refused (pass them as figma_prototype_url), as are v0 share links.
  • figma_prototype_url — a public Figma prototype link, stored embed-only under https://www.figma.com/proto/…: required on prototypeTask (the task’s prototype), and on any other type except websiteTest and calendar it attaches the prototype as the question’s asset. On a prototypeTask, replacing the link clears an existing props.goalNode, and a non-empty goalNode in the same item is refused.
  • display_order — position (new questions are auto-ordered if omitted).

Question references (mentions)

content can reference an earlier answer with either:
  • {{Q:<question_id>}} — the complete answer.
  • A type-specific property token — one option response from a structured answer, such as:
    • {{Q:<matrix_question_id>.ratingForItem[0]}}
    • {{Q:<ranking_question_id>.rankOfOption[0]}}
    • {{Q:<ranking_question_id>.optionAtRank[0]}}
    • {{Q:<allocation_question_id>.allocationForItem[0]}}
Property indices are zero-based. Do not construct property tokens with a generic .option[index] selector; it is not supported. Call List available references for the destination question’s position and copy the returned template verbatim. References are validated on write, and invalid property names, indices, missing questions, or forward references fail with 422 and an errors array.

Response

string[]
IDs of newly created questions, in request order: created_question_ids[i] is the ID of the i-th item without an id. Items with an id are skipped, and display_order or question_group_id on an item does not change its position in this list.
string[]
IDs of updated questions, in request order.
To map each ID back to the question you sent, walk your questions array and take the next ID from created_question_ids for each item without an id, and the next ID from updated_question_ids for each item with one.

Errors

The batch is validated before anything is written. When one item is invalid, the request fails with 400, 403, or 404 and a detail that names the item by its zero-based position, for example "questions[2]: Unknown question type 'notAType'. ...". Fix that item and resend the whole batch. Two checks run after the rows are written: {{Q:...}} references on every item, and checks against earlier answers on new questions. A 422 from either one leaves the batch written and does not return the new IDs. Retrying the same request with the same Idempotency-Key returns the same 422 without creating the questions again; fix the batch and send it with a new key.

Retries

Send an Idempotency-Key header (a UUID you generate per batch works well) and you can resend the same request after a timeout, a network error, or a 5xx without creating questions twice. A retry with the same key and the same body returns the same created_question_ids as the first attempt, and the questions are written once, even when the retries overlap. The key only covers that exact body: the same key with a different body is treated as a new batch. Without the header, every request creates new questions. The example below creates one new question and updates an existing one (8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d), piping that existing question’s answer into the new question’s text. References must point at questions that already exist in the study — use List available references to discover valid templates.