Preview or revise a study research plan

Let the research-planning model capture intent, main source, all attached assets, questions, optional methods, semantic outputs, missing inputs, confirmation questions, and a proposed response contract for every question. Clients can deterministically edit response formats and assign durable assets to exact questions. Pass questions instead of request to transcribe a fixed instrument exactly: text, order, ids, and per-item response contracts are stored as given and no planning model runs; a revision of a fixed instrument that sends no questions, request or refinement (for example only answers) keeps its saved questions. Pass methodId (a Study template's configuration.methodId, or any method list_research_methods reports as executable) to run the first module with that registered method, as the web app does: the planner plans for it, or a fixed instrument keeps its questions as supplementary questions; methods that design their own tasks (Van Westendorp, Gabor-Granger, MaxDiff, conjoint, Kano, NPS, TURF and others) add them at execution from the method configuration. Revisions keep the selected method unless another is named. Fetchable remote files are copied into durable Minds chat storage before the versioned draft is saved. Local file:// paths are not uploads. A draft that research-runs would refuse is never returned as confirmable: a method configuration the planner left empty is filled from the request where possible, and anything still missing (price currency, price basis, method configuration, expected respondent material) is returned as a confirmation question with startReadiness and status: needs_input; revise with answers keyed by question id, using the option id for a choice question. This endpoint never executes research.

post/api/v1/studies/{studyId}/research-plans/preview

Request

Base URL: https://api.getminds.ai
URL: https://api.getminds.ai/api/v1/studies/{studyId}/research-plans/preview
Auth: HTTP bearer

Path parameters

studyIdstring uuid required

Request body

loadLatestboolean

Read the latest owned draft without planning or saving. Requires draftPlanId; cannot be combined with edits or planner inputs.

requeststring

studyLocale'en' | 'es' | 'fr' | 'de' | 'zh' | 'tr' | 'ar' | 'ja' | 'ko'

Language used for the plan and its eventual study output.

sourcePolicy'request_only' | 'auto'

Evidence policy stored in this exact draft revision. request_only keeps a controlled Study closed to retrieved Mind documents and live web. auto is an explicit experimental opt-in to relevant Mind-knowledge retrieval; response-mode rules still control live web search.

videoAnalysisStyle'record' | 'analyst'

Register of the one video summary every Mind of this run reads. record writes down the spoken script, the visible scenes and the on-screen text. analyst deliberately reproduces the pre-2026-09 prompt, which reads tone and intent and raises the study's positive rating bias; use it only to replicate an older run.

suggestQuestionStimuliboolean

Default true. Lets the planner assign each attached file or website to one or more questions; the ids appear as attachmentIds on those questions. Pass false to keep questions unassigned unless questionAttachments names them.

draftPlanIdstring uuid

revisioninteger

refinementstring

answersobject

questionResponsesobject

Explicit response-format edits keyed by question ID from the current draft.

methodIdstring

Registered research method for the first module, such as a Study template's configuration.methodId (van-westendorp, maxdiff, conjoint, nps, turf, …). Must be executable (list_research_methods); an unknown or unavailable method is a 400. Its configuration is filled from the request, questions and answers where they state it, otherwise asked as a confirmation question. Omitted on a new draft: the planner chooses, and a fixed instrument runs as Custom research (guided-research). Omitted on a revision: the method selected earlier is kept. Cannot be combined with edits or loadLatest.

idempotencyKeystring

Retry-safety key. A repeated preview with the same key returns the draft revision the first attempt saved (replayed: true) instead of planning again. The Idempotency-Key header takes precedence.

Response

Saved plan draft, per-question response contracts, and confirmation questions.

Changes

No recorded changes to this operation across all 1 revision of this API.