Skip to main content
PUT
Updates a question. Only the fields you send change, and props is merged with the existing props. Returns 204 No Content.
string
required
The question ID.
string
New question text. {{Q:...}} references are validated (422 on invalid references).
string
Private AI guidance.
string
How the question’s display conditions combine: all shows it only when every condition is met, any when one is. Any other value, or null, returns 422.
integer
New position.
object
Settings to merge into the existing props. See Editing multiple-choice options for how exclusive options are kept in sync, Matrix Allocation not-applicable cells for allocationWithMatrix, and Checks against earlier answers for number and allocation validation against an earlier answer.
object[]
Replaces the media assets array. Keep each asset’s stable url from List questions. download_url and download_url_expires_at are read-only and are discarded if sent back. A file from Create asset upload can’t be referenced here until it is verified: attach it with asset: { "upload_id" } instead, or the request returns 400.
object | null
Set the question’s media, replacing the default-language asset (translated variants are kept). Either a verified upload, { "upload_id": "…", "layout": "fullScreen" | "inline", "sizing": "fit" | "scroll", "max_width_percent": 1–100, "autoplay": bool, "loop": bool }, or a copy of another question’s media in the same study, { "copy_from_question_id": "…", "layout": … } (omit layout to keep the source’s layout and width; an upload defaults to fullScreen). The ticket must be ready (see Complete asset upload) and created by the same caller (the same user for an MCP ticket, the same API key for an organization key’s ticket). autoplay and loop apply to videos only. Send null to remove the asset. Not accepted on websiteTest, prototypeTask, or calendar questions. Uploaded images get an automatic description the AI interviewer uses; a copy keeps the source’s. Cannot be combined with assets, embedded_website_url, or figma_prototype_url in the same request.
string
Show an https:// page in a frame beside the question, replacing the default-language asset. http:// is refused. Figma links (figma.com) are refused too: pass a Figma prototype as figma_prototype_url instead, while a published Figma Make app’s figma.site URL is fine. v0 share links are refused as well (deploy the app and use its vercel.app URL). Not accepted on websiteTest (use props.url), prototypeTask, or calendar questions. Remove it with "asset": null.
string
A public Figma prototype link (https://www.figma.com/proto/…; other https://*.figma.com hosts are accepted and stored under that prefix). Required on prototypeTask, where it is the task’s prototype. On any other type except websiteTest and calendar it attaches the prototype as the question’s asset, the same as Add asset > Figma Prototype in the editor, replacing the default-language asset. Stored as an embed-only prototype. On a prototypeTask, replacing the link clears an existing props.goalNode, because an embed-only prototype has no frames to check a goal against, and sending a non-empty goalNode in the same request is refused.

Adding an earlier answer

Mentions are stored directly in content. Use {{Q:<question_id>}} for the complete earlier answer. For one response from a matrix, ranking, allocation, or card-sort question, first call List available references with before_question_id set to this question, then copy the returned property template verbatim. For example, this inserts the rating for the first matrix item:
Property indices are zero-based. Invalid property names or indices return 422.

Editing multiple-choice options

Multi-select multipleChoice questions can mark options such as “None of the above” as exclusive in props.exclusiveOptions. Entries are the option text and must exactly match an entry in props.options (case-sensitive), otherwise the request is rejected with 400. You don’t need to resend exclusiveOptions when you edit options. If you omit it, or send it unchanged, the API keeps it in sync for you:
  • Renaming one option keeps its exclusive marker (the marker follows the new text).
  • Removing an option drops its marker.
  • Setting isMultiSelect to false clears all markers, since exclusivity only applies to multi-select.
To change which options are exclusive, send the new exclusiveOptions list explicitly, matching the final options. Question quotas on the options follow the same rule: renaming one option moves its quota to the new text, and removing an option drops its quota. Rename options one at a time, without adding or removing others in the same request, so a quota is never mistaken for a removed option’s.

Checks against earlier answers

number and allocation questions can carry checks of the answer against an earlier answer in props.earlierAnswerChecks. Each check has an operation (<, <=, ==, >=, or >) and a source: the earlier question’s questionId, plus option (the exact option text) when the earlier question is an allocation.
  • A number question holds a list of checks.
  • An allocation question holds either {"target": "total", "checks": [...]} — the total is compared, and the fixed limit (hasLimit) no longer applies — or {"target": "options", "checks": {"<option text>": [...]}} with one list per option of this question. Keys must exactly match entries in props.options.
The earlier question must be a number or allocation question that comes before this one on every path a participant can take, and it must still have the option named; otherwise the request is rejected with 422 and an errors array. Renaming an option of the earlier question that a check names is rejected the same way — update the check first. When you edit this question’s own options, per-option checks follow a renamed option and are dropped for a removed one, like exclusiveOptions.

Matrix Allocation not-applicable cells

allocationWithMatrix questions can mark cells as not applicable in props.naCells, a list of {"row": ..., "column": ...} objects. row and column must exactly match an entry in props.options and props.columns, otherwise the request is rejected with 400. Participants see these cells as N/A and can’t enter a value; they don’t count toward the column’s total, and answers store "N/A" in them. Like exclusiveOptions, you don’t need to resend naCells when you edit options or columns: renaming one row or column keeps its cells, and removing one drops them. Send an empty list to clear all N/A cells.

Uploading an asset

Supported uploads are JPEG, PNG, GIF, WebP, and BMP images; MP4, WebM, and QuickTime videos; and PDFs, up to 50 MB per file. BMP uploads accept image/bmp and image/x-ms-bmp. This endpoint also accepts multipart/form-data to attach a media file directly:
  • file — the media file.
  • asset_layout — fullScreen (default) or inline.
  • asset_sizing — optional sizing mode.
  • asset_max_width_percent — optional, integer from 1 to 100 capping the width at that percent of the question column. Requires asset_layout=inline and an image or video. Omit or send 100 for full width.
  • Other fields (content, props as JSON strings, etc.) may be sent as form fields.