Ask One Standalone Audience Question
ask_audienceDestructive
Accepts one standalone question request for an existing Audience and creates a private Study. Returns IDs and links; preparing is not question admission. Report the current phase from the receipt and progress.
The server may reword a context-dependent question. The accepted task and its answer contract are returned with the original request. Ambiguous requests or generated questions return planning_required before execution.
Out of scope: a questionnaire, battery, section or any request with two or more known questions. That complete set runs as one planned multi-question block inside a Study.
Attachments can be URLs, Minds uploads or files shared in the conversation (uploaded or generated images, PDFs).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional name for the Study created to ask this question. Defaults to the Audience name. | |
| audience | No | Which Audience to ask. Give the id when known, otherwise the name. | |
| question | Yes | Exactly one respondent-visible standalone question for every Mind in the Audience. The system may classify or reformat it, but any text in this field can reach the Minds and influence their answers. Include only the question and the instructions the Minds should receive. Material the question is about (a pasted newsletter, email, ad copy or concept text) goes in textAttachments, verbatim, not here. Never place planner-only or MCP-client orchestration instructions here. If the question offers a fixed set of answer options, say so in the text as the respondent would read it. The research reader identifies the question and its answer contract together. Include the complete authored labels, ordering and selection instructions. Numbered answer options do not by themselves make a request a multi-question battery. An invalid or ambiguous reading stops for retry or planning before execution. | |
| attachments | No | Files/images processed once and given to every Audience member as context. Accepts a public HTTP(S) URL or a file already in the user's Minds uploads under chat/<userId>/ (its storage path or its /api/uploads/chat/ URL). MCP cannot read a local path. Files shared in the conversation (uploaded or generated images, PDFs, documents) go in the tool's top-level conversationFiles field where the tool has one; elsewhere a PDF or image without a public URL has no MCP route and is uploaded in the Minds app first. Plain text contents (UTF-8 text, Markdown, CSV, JSON) can go to import_audience_sources. External URLs are copied into Minds storage before a Study is saved or run. temp/, portfolio/ and context/ paths and /api/uploads/file-access/ URLs belong to other owners and are not accepted. A Study does not start until Minds can read every file. | |
| textAttachments | No | Pasted material the question is about: a newsletter, an email, ad copy, a concept or any other text the user shared and wants the Minds to react to. Put it here verbatim, one entry per piece, instead of inside the question. Each entry is stored as a Markdown file and given to the Minds like an uploaded attachment; a brief or background note sent here is read as such and not shown to them. | |
| conversationFiles | No | Stimulus files given to every Audience member, alongside any attachments. Files shared in this conversation: uploaded or generated images, PDFs, documents. Each is copied into Minds storage on receipt; its file_id is its attachment id. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| runId | No | Durable run identifier. | |
| locale | No | Study display locale. | |
| status | No | preparing when the request was accepted for durable interpretation but no question was submitted; queued once a question was submitted; or planning_required when the request needs a reviewed plan and explicit confirmation before execution. | |
| apiBase | No | Minds base URL. | |
| studyId | No | Study containing this request and, once admitted, its question. | |
| accepted | No | True when durable request preparation was accepted; this does not mean a respondent question was submitted. | |
| question | No | The verified respondent question, when returned. Its text alone does not report whether the request is queued, the Minds are answering or answers are complete; use the current request's receipt and progress. | |
| planLimit | No | Present when a plan limit refused, truncated or stopped Study work. | |
| questionId | No | Logical request or question identifier. Present during preparation as the exact clientRequestId; use this returned questionId with studyId on the first get_study_status check for the current request. It follows preparation and any admitted question, independently of operationId. | |
| waitingFor | No | Present when the question is queued behind Minds still training: how many it waits for. It starts once they are ready; nothing has been answered yet. | |
| operationId | No | Opaque durable preparation operation identifier, present while the request is being interpreted. This is separate from questionId and must not be passed as a question filter. | |
| workspaceUrl | No | Authenticated Minds workspace link for the Study. | |
| questionnaire | No | For planning_required when the uploaded files hold a questionnaire: its verbatim questions with their answer formats, the document's skip rules, changed answer labels, pictures and set-aside parts, saved as the exact draft draftPlanId at revision. Nothing ran yet: after the person's explicit confirmation, start that draft with start_study_run. | |
| sharedStudyUrl | No | Public share link, or null when link sharing is off. | |
| clientRequestId | No | The accepted logical request identifier. A preparing receipt also returns this exact value as questionId for progress reads. | |
| executionStarted | No | False when no respondent question was submitted, including accepted preparation and planning_required. Submission or queueing does not establish that Minds are answering; use the current request's progress to report answering or completion. | |
| proposedQuestions | No | For planning_required: the respondent questions detected or proposed. |