openapi: 3.2.0 info: title: Minds Public Studies API version: v1 description: 'OpenAPI 3.1.0 spec for the Minds public API (https://getminds.ai/api/v1 / https://api.getminds.ai/v1). Generate a typed TypeScript client by running an OpenAPI generator (e.g. `openapi-typescript`) against `/_openapi.json`. Auth: send `Authorization: Bearer minds_…_key`; create keys in Settings → API Keys.' servers: - url: https://api.getminds.ai description: Production (api subdomain) - url: https://getminds.ai description: Production (apex) security: - ApiKeyAuth: [] tags: - name: Studies paths: /api/v1/studies/{studyId}: delete: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '204': description: Study deleted. '400': description: Invalid study ID, or the Study is not in study mode. '401': description: Missing or invalid authentication. '403': description: Only the study owner may delete it. '404': description: Study not found. operationId: deleteStudy summary: Delete a study description: Delete a Study owned by the authenticated user. tags: - Studies security: - ApiKeyAuth: [] get: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Study details. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/StudyDetail' '400': description: Invalid study ID, or the Study is not in study mode. '401': description: Missing or invalid authentication. '403': description: The caller cannot access this study. '404': description: Study not found. operationId: getStudy summary: Get a study description: Return a Study with its attached audiences, Minds, and messages. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/analytics: get: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Canonical study statistics. '401': description: Missing or invalid authentication. '403': description: The caller cannot access this study. '404': description: Study not found. operationId: getStudyAnalytics summary: Get canonical study analytics description: Compute scale, categorical, multiselect, and qualitative statistics from answered study questions. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/ask: post: parameters: - in: path name: studyId required: true description: Study UUID. schema: type: string format: uuid responses: '200': description: SSE stream of study generation events, or a durable queue receipt when responseMode is queued. content: text/event-stream: schema: type: string description: Server-Sent Events stream. Each `data:` payload is a JSON object matching `StudyAskSseEvent`. examples: result: summary: Final result event value: 'data: {"type":"result","outputData":{"title":"Rate this 1-5","type":"scale","audiences":[]},"outputType":"bar"} ' application/json: schema: type: object required: - status - count - questionBlockId - clientRequestId - queuedMessage properties: status: type: string enum: - queued jobId: type: string count: type: integer minimum: 1 questionBlockId: type: string description: Canonical Question Block correlation ID. questionAudienceId: type: string deprecated: true description: Legacy alias for questionBlockId. clientRequestId: type: string format: uuid queuedMessage: type: boolean enum: - true x-event-schema: $ref: '#/components/schemas/StudyAskSseEvent' '400': description: Missing question, invalid study ID, invalid model override, no attached audiences, or no minds in selected audiences. '401': description: Missing or invalid API key. '403': description: 'Caller cannot access the study, or plan message limit reached (`code: PLAN_LIMIT`).' '404': description: Study does not exist. '500': description: Internal server error. operationId: askStudy summary: Ask a study question description: Send a question to all minds in a study or a selected subset of attached audiences. Returns a Server-Sent Events stream with start, optional classification, per-mind answers, aggregation progress, final output data, and done events. tags: - Studies security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StudyAskRequest' examples: basic: summary: Ask all audiences value: question: On a scale of 1-10, how likely are you to recommend this product? withContext: summary: Ask selected audiences with context value: question: What should we improve in this onboarding flow? audienceIds: - 550e8400-e29b-41d4-a716-446655440000 attachments: - url: https://example.com/onboarding.pdf name: Onboarding flow type: application/pdf links: - label: https://competitor.example.com/onboarding id: competitor-onboarding /api/v1/studies/{studyId}/export-download: get: parameters: - in: path name: studyId required: true description: Study UUID. schema: type: string format: uuid - in: query name: jobId required: false description: Completed export job ID. Optional when the study already has a persisted export. schema: type: string - in: query name: kind required: false description: Export kind to download. Without jobId, resolves the latest completed artifact of this kind. schema: type: string enum: - executive_brief - full_report - raw_data - in: query name: format required: false description: Export format to download. Without jobId, resolves the latest completed artifact in this format. schema: type: string enum: - pdf - html - png - md - docx - pptx - csv - xls - sav responses: '302': description: Redirect to a short-lived signed Storage download URL. '400': description: Job is not completed, unsupported kind/format, or the Study is not in study mode. '401': description: Missing or invalid API key. '403': description: Caller cannot access the study. '404': description: Study, export job, or generated file does not exist. '500': description: Storage not configured, download failed, or internal server error. operationId: downloadStudyExport summary: Download a study export description: Authorize access, then redirect to a short-lived signed Storage URL for a completed export in any supported format. Pass `jobId` for one exact artifact, or `kind` and `format` for the latest completed export of that type. With no query the latest persisted full-report PDF is served. The web service never buffers the export file. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/export-status: get: parameters: - in: path name: studyId required: true description: Study UUID. schema: type: string format: uuid - in: query name: jobId required: false description: Specific export job ID. Omit to return the latest persisted export when available. schema: type: string - in: query name: kind required: false description: Expected export kind for job-specific polling. schema: type: string enum: - executive_brief - full_report - raw_data - in: query name: format required: false description: Expected export format for job-specific polling. schema: type: string enum: - pdf - html - png - md - docx - pptx - csv - xls - sav responses: '200': description: Export status. content: application/json: schema: $ref: '#/components/schemas/StudyExportStatusResponse' '400': description: Invalid study ID or unsupported study flow. '401': description: Missing or invalid API key. '403': description: Caller cannot access the study. '404': description: Study, export job, or completed export does not exist. '500': description: Internal server error. operationId: getStudyExportStatus summary: Get study export status description: Check the status of any queued study export. If `jobId` is omitted, the endpoint can still recover the latest legacy full-report PDF. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/export: post: parameters: - in: path name: studyId required: true description: Study UUID. schema: type: string format: uuid responses: '200': description: Export queued. content: application/json: schema: $ref: '#/components/schemas/StudyExportJobResponse' '400': description: Invalid study ID, unsupported study flow, or invalid export format. '401': description: Missing or invalid API key. '403': description: Caller cannot access the study. '404': description: Study or scheduled run does not exist. '500': description: Internal server error. operationId: exportStudy summary: Queue a study export description: Queue any supported study export in the background processor. Poll `getStudyExportStatus` with the returned job ID and download the storage-backed artifact when complete. tags: - Studies security: - ApiKeyAuth: [] requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/StudyExportRequest' examples: executiveBriefPdf: summary: Executive summary PDF export value: kind: executive_brief format: pdf fullReportDocx: summary: Full report DOCX export value: kind: full_report format: docx rawDataCsv: summary: Raw answers CSV export value: kind: raw_data format: csv rawDataSav: summary: Raw answers SPSS export value: kind: raw_data format: sav /api/v1/studies/{studyId}/heatmaps/{messageId}/export-download: get: parameters: - in: path name: studyId required: true schema: type: string format: uuid - in: path name: messageId required: true schema: type: string responses: '200': description: Website heatmap ZIP archive. operationId: downloadStudyWebsiteHeatmapExport summary: Download a website heatmap export tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/heatmaps/{messageId}/export-status: get: parameters: - in: path name: studyId required: true schema: type: string format: uuid - in: path name: messageId required: true schema: type: string responses: '200': description: Website heatmap export status. operationId: getStudyWebsiteHeatmapExportStatus summary: Get website heatmap export status tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/heatmaps/{messageId}/export: post: parameters: - in: path name: studyId required: true schema: type: string format: uuid - in: path name: messageId required: true schema: type: string responses: '200': description: Cached archive or queued export job. operationId: exportStudyWebsiteHeatmap summary: Export a website heatmap archive tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/heatmaps/{messageId}: get: parameters: - in: path name: studyId required: true schema: type: string format: uuid - in: path name: messageId required: true schema: type: string - in: query name: assetKey schema: type: string responses: '200': description: Selected heatmap and queue state; GET also returns saved assetHeatmaps. operationId: getStudyHeatmap summary: Read saved question heatmaps; assetKey selects one video or image tags: - Studies security: - ApiKeyAuth: [] post: parameters: - in: path name: studyId required: true schema: type: string format: uuid - in: path name: messageId required: true schema: type: string responses: '200': description: Selected heatmap and queue state; GET also returns saved assetHeatmaps. operationId: startStudyHeatmap summary: Analyze an assigned question asset; completed asset results are reused tags: - Studies security: - ApiKeyAuth: [] requestBody: content: application/json: schema: type: object properties: assetKey: type: string description: 'Stable asset key from the question attachment: upload path or normalized URL.' /api/v1/studies/{studyId}/invitations: post: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Invitations created and delivery failures, if any. '401': description: Missing or invalid authentication. '404': description: Study not found or not owned by the caller. operationId: inviteStudyCollaborators summary: Invite study collaborators description: Invite people to collaborate on an existing study, matching the web app invitation flow. tags: - Studies security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - emails properties: emails: type: array items: type: string format: email minItems: 1 maxItems: 100 role: type: string enum: - member - admin default: member inviteEntireTeam: type: boolean default: false /api/v1/studies/{studyId}/messages/{messageId}/answers: get: parameters: - name: studyId in: path required: true schema: type: string format: uuid - name: messageId in: path required: true schema: type: string description: Assistant message CUID returned in recentResults by get_study_status. - name: scope in: query schema: type: string enum: - full - preview default: full responses: '200': description: Sanitized question output, including per-Audience answers. content: application/json: schema: type: object required: - messageId - outputData properties: messageId: type: string outputData: type: object additionalProperties: true '400': description: Invalid Study ID, message ID or scope. '401': description: Missing or invalid authentication. '403': description: Caller cannot access the Study. '404': description: No assistant answer with this message ID belongs to the Study. operationId: getStudyMessageAnswers summary: Read individual answers for one Study question description: Hydrates the original per-Mind responses omitted from the compact Study transcript. Requires access to the Study and an assistant message belonging to that Study. Full reads return all responses for this message; preview reads return representative responses. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/research-plans/preview: post: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Saved plan draft, per-question response contracts, and confirmation questions. content: application/json: schema: type: object required: - data properties: data: type: object properties: {} '400': description: Invalid request. '401': description: Unauthorized. '403': description: Study access denied. '404': description: Study or draft not found. '409': description: Draft revision conflict. operationId: previewStudyResearchPlan summary: Preview or revise a study research plan description: '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. Fetchable remote files are copied into durable Minds chat storage before the versioned draft is saved. Local file:// paths are not uploads. This endpoint never executes research.' tags: - Studies security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object properties: loadLatest: type: boolean description: Read the latest owned draft without planning or saving. Requires draftPlanId; cannot be combined with edits or planner inputs. edits: type: object description: Deterministic edits to a saved revision. Preserves methods and source policy; cannot be combined with planner inputs. additionalProperties: false properties: objective: type: string maxLength: 2000 promptContent: type: string maxLength: 20000 questions: type: array minItems: 1 maxItems: 200 items: type: object additionalProperties: false required: - id - moduleId - text - response properties: id: type: string moduleId: type: string text: type: string maxLength: 2000 attachmentIds: type: array items: type: string request: type: string studyLocale: type: string enum: - en - es - fr - de - zh - tr - ar - ja - ko description: Language used for the plan and its eventual study output. sourcePolicy: type: string enum: - request_only - auto default: request_only description: 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. mindSourcePolicyOverrides: type: array maxItems: 2000 description: Experimental checksum-locked Mind assignments. Each Mind UUID may appear once. Unlisted Minds use sourcePolicy; persisted knowledge_only locks remain stricter. items: type: object required: - mindId - sourcePolicy additionalProperties: false properties: mindId: type: string format: uuid sourcePolicy: type: string enum: - request_only - auto source: type: object description: The main source. Prompt content is exact respondent-visible material and is separate from planner-only request text. properties: kind: type: string enum: - prompt - website - image - video - document - questionnaire - other label: type: string url: type: string format: uri mimeType: type: string content: type: string attachments: type: array description: Files and website assets available to the confirmed run (one question block). Multi-asset blocks require complete question assignments and coverage of every asset; each question receives only its own assets. Empty lists explicitly mean no assets. Remote file URLs are durably imported; kind website remains a website. items: type: object properties: kind: type: string enum: - website id: type: string name: type: string url: type: string path: type: string mimeType: type: string type: type: string questionAttachments: type: array description: One-based question-to-attachment-id mapping. Multi-asset blocks require every question to be mapped and every asset to be used. Empty attachmentIds means no assets. Each question may appear at most once. items: type: object required: - questionNumber - attachmentIds additionalProperties: false properties: questionNumber: type: integer minimum: 1 attachmentIds: type: array minItems: 0 uniqueItems: true items: type: string suggestQuestionStimuli: type: boolean description: 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. draftPlanId: type: string format: uuid revision: type: integer minimum: 1 refinement: type: string answers: type: object additionalProperties: type: string questionResponses: type: object description: Explicit response-format edits keyed by question ID from the current draft. idempotencyKey: type: string maxLength: 200 description: '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.' /api/v1/studies/{studyId}/research-runs/{runId}: get: parameters: - in: path name: studyId required: true schema: type: string format: uuid - in: path name: runId required: true schema: type: string format: uuid responses: '200': description: Durable study status and immutable response contracts. content: application/json: schema: type: object required: - data properties: data: type: object properties: status: type: string enum: - queued - running - completed - partial - failed - cancelled - plan_limited description: Partial means settled questions have missing respondent answers or some questions failed. It is terminal collection, not complete evidence. progress: type: object properties: total: type: integer settled: type: integer failed: type: integer partial: type: integer description: Questions with recorded incomplete respondent coverage. skipped: type: integer pct: type: integer description: Settled-question progress, not respondent coverage. respondentStimulusDelivery: type: object description: Configured stimulus channel, not proof of delivery. The frozen base Mind profile excludes per-run stimulus. properties: channel: type: string enum: - prompt_evidence - website_analysis - file_analysis - none mindProfileIncludesStimulus: type: boolean enum: [] verification: type: string enum: - configuration_only description: type: string respondentMediaEvidence: type: object description: Per-Mind video evidence audit. Verified means every recorded answer for every video question has matching audiovisual receipts and accepted-call SDK media prompt hashes. properties: version: type: string enum: - respondent-media-evidence-v1 status: type: string enum: - not_applicable - verified - incomplete videoQuestionCount: type: integer answerCount: type: integer verifiedAnswerCount: type: integer visualContract: type: string enum: - scene-sampled-frames speechContract: type: string enum: - full-transcript soundtrackContract: type: string enum: - bounded-analysis failures: type: array items: type: object additionalProperties: true questionAttachments: type: array items: type: object additionalProperties: true calculations: type: array items: type: object additionalProperties: true '401': description: Unauthorized. '403': description: Study access denied. '404': description: Study not found. operationId: getStudyResearchStudy summary: Get research study status description: Return durable progress, the immutable confirmed plan snapshot with per-question response contracts, response artifacts, deterministic method calculations, and stage readiness for a confirmed multi-question Study run. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies/{studyId}/research-runs: post: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Study queued with its immutable confirmed response contracts. content: application/json: schema: type: object required: - data properties: data: type: object properties: {} '400': description: Plan is incomplete, unconfirmed, invalid, unavailable, or not executable. '401': description: Unauthorized. '403': description: Study or draft access denied. '404': description: Study or draft not found. '409': description: Draft already confirmed for another run, or a Mind in an attached Audience has not finished training (legacy code `PANEL_MINDS_NOT_READY`, with `data.notReady` naming them). Retry once training completes. '422': description: Required respondent-visible image, file, or URL could not be read. The Study is not queued and no quota is used. operationId: runStudyQuestions summary: Confirm and run a multi-question Study block description: Execute an exact saved research-plan revision after explicit confirmation, including every confirmed per-question response and attachment contract. The server, not the client or model, marks required capabilities reviewed and enforces advanced-method opt-in, method availability, and durable media resolution. tags: - Studies security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - draftPlanId - revision - confirmation properties: draftPlanId: type: string format: uuid revision: type: integer minimum: 1 confirmation: type: object required: - accepted properties: accepted: type: boolean enum: - true advancedMethodOptIn: type: boolean audienceIds: type: array items: type: string format: uuid idempotencyKey: type: string format: uuid modelConnection: type: object additionalProperties: false required: - id - revision properties: id: type: string format: uuid revision: type: integer minimum: 1 description: Verified caller-team connection for Mind answers and verbatim rendering. Pinned at confirmation; retries must keep the same selection. Supporting analysis retains platform models. /api/v1/studies/{studyId}/sharing: put: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Updated sharing state and public share ID. '401': description: Missing or invalid authentication. '404': description: Study not found or not owned by the caller. operationId: updateStudySharing summary: Update study link sharing description: Enable or disable the public link for an existing study. Enabling also exposes its attached Audiences and Minds, matching the web app. tags: - Studies security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - isLinkSharingEnabled properties: isLinkSharingEnabled: type: boolean /api/v1/studies/{studyId}/summary: get: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Persisted semantic summary. content: application/json: schema: type: object required: - data properties: data: type: object '400': description: Study is not in study mode. '401': description: Unauthorized. '403': description: Study access denied. '404': description: Study not found. operationId: getStudySemanticSummary summary: Get a study semantic summary description: Return the persisted whole-study summary, semantic output blocks, staleness, and message coverage. Renderers are hints; consumers may introduce new UI logic without changing evidence contracts. tags: - Studies security: - ApiKeyAuth: [] post: parameters: - in: path name: studyId required: true schema: type: string format: uuid responses: '200': description: Generated semantic summary. content: application/json: schema: type: object required: - data properties: data: type: object '400': description: Study is not in study mode, or does not have enough content. '401': description: Unauthorized. '403': description: Study access denied. '404': description: Study not found. operationId: refreshStudySemanticSummary summary: Generate or refresh a study semantic summary description: Generate and persist a whole-study summary with flexible semantic blocks. Visual-source evidence is represented as heatmaps rather than generic distribution charts. tags: - Studies security: - ApiKeyAuth: [] /api/v1/studies: get: parameters: - in: query name: limit required: false description: Max studies per page. schema: type: integer minimum: 1 maximum: 100 default: 100 - in: query name: offset required: false description: Number of studies to skip. schema: type: integer minimum: 0 default: 0 responses: '200': description: A page of studies. content: application/json: schema: type: object required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/StudySummary' pagination: $ref: '#/components/schemas/Pagination' '401': description: Missing or invalid API key. '500': description: Internal server error. operationId: listStudies summary: List studies description: List Studies owned by the authenticated user. Each Study embeds its attached Audiences and their member Minds. tags: - Studies security: - ApiKeyAuth: [] post: parameters: [] responses: '201': description: Study created. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/StudyCreated' '400': description: Missing `name`. '401': description: Missing or invalid API key. '403': description: 'Plan limit reached (`code: PLAN_LIMIT`).' '404': description: One or more Audience IDs were not found or are inaccessible to the caller. '500': description: Internal server error. operationId: createStudy summary: Create a Study description: Create a Study and optionally attach existing or newly created Audiences with audienceIds and audienceConfigs. tags: - Studies security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Study name. audienceIds: type: array items: type: string format: uuid description: Audience IDs to attach. De-duplicated server-side. audienceConfigs: type: array description: Audiences to create atomically before attaching them to the Study. items: type: object required: - name - mindIds properties: name: type: string mindIds: type: array items: type: string format: uuid isLinkSharingEnabled: type: boolean description: Enable public link sharing for the Study and its attached Audiences/Minds. components: schemas: StudyAudience: type: object required: - id - name - minds properties: id: type: string format: uuid name: type: string minds: type: array items: $ref: '#/components/schemas/StudyMind' StudyOutputAudience: type: object required: - audience - value - answers properties: audience: type: string deprecated: true description: Deprecated alias for audience. value: type: string alignmentScore: type: integer minimum: 0 maximum: 100 answers: type: array items: $ref: '#/components/schemas/StudyOutputAnswer' StudyAskClassificationEvent: type: object required: - type - classification properties: type: type: string enum: - classification classification: $ref: '#/components/schemas/StudyQuestionClassification' StudyExportJobResponse: type: object required: - data properties: data: type: object required: - kind - format - jobId - status properties: kind: type: string enum: - executive_brief - full_report - raw_data format: type: string enum: - pdf - md - docx - pptx - csv - xls - sav jobId: type: string status: type: string enum: - queued StudyAnswerProvenance: type: object required: - origin - sourcePolicy - retrievalAttempted - retrievalChunksFound - retrievalChunksUsed - evidenceSourceTypes - fallbackStatus - unsupported - sharedEmbeddingReuse - recordedAt - verifier properties: origin: type: string description: Canonical answer origin. `group_grounding` was renamed to `audience_grounding`; it is still listed so a response recorded before the rename validates. enum: - cited_sources - mind_knowledge - mind_personality - request_evidence - audience_grounding - group_grounding - unsupported originLegacy: type: string deprecated: true description: Pre-rename spelling of `origin`, present only when one exists. Switch to `origin`; this field will be removed. enum: - group_grounding sourcePolicy: type: string enum: - auto - knowledge_only retrievalAttempted: type: boolean retrievalChunksFound: type: integer minimum: 0 retrievalChunksUsed: type: integer minimum: 0 evidenceSourceTypes: type: array items: type: string fallbackStatus: type: string enum: - grounded - persona_profile - uncertainty_required unsupported: type: boolean sharedEmbeddingReuse: type: boolean recordedAt: type: string format: date-time verifier: type: string enum: - study-answer-provenance-v1 StudyAskDoneEvent: type: object required: - type properties: type: type: string enum: - done StudyMessage: type: object required: - id - role - content - metadata - createdAt properties: id: type: string role: type: string content: type: string metadata: {} createdAt: type: string format: date-time Pagination: type: object required: - total - limit - offset properties: total: type: integer description: Total matching rows. limit: type: integer description: Page size requested. offset: type: integer description: Number of rows skipped. StudyOutputData: type: object required: - title - type - audiences properties: title: type: string type: type: string enum: - scale - categorical - multiselect - qualitative classification: $ref: '#/components/schemas/StudyQuestionClassification' categoryCodebook: type: array items: $ref: '#/components/schemas/StudyCategoryCodebookEntry' audiences: type: array deprecated: true description: Deprecated alias for audiences. items: $ref: '#/components/schemas/StudyOutputAudience' StudyExportRequest: type: object properties: kind: type: string enum: - executive_brief - full_report - raw_data default: full_report format: type: string enum: - pdf - md - docx - pptx - csv - xls - sav default: md length: type: string enum: - short - standard - detailed default: standard force: type: boolean default: false scheduledRunId: type: string format: uuid StudyMind: type: object required: - id - name properties: id: type: string format: uuid name: type: string discipline: type: - string - 'null' profileImageUrl: type: - string - 'null' format: uri StudyAskAggregatingEvent: type: object required: - type properties: type: type: string enum: - aggregating StudyCitationSource: type: object required: - id - title - sourceType properties: id: type: string title: type: string url: type: string format: uri domain: type: string sourceType: type: string enum: - mind_knowledge - web similarity: type: number StudyAskStartEvent: type: object required: - type - total properties: type: type: string enum: - start total: type: integer description: Total number of minds that will answer. StudyContextLink: type: object properties: label: type: string description: URL or display label. url: type: string description: URL to fetch when separate from `label`. id: type: string StudyAskResultEvent: type: object required: - type - outputData - outputType properties: type: type: string enum: - result outputData: $ref: '#/components/schemas/StudyOutputData' outputType: type: string enum: - bar StudyAskRequest: type: object required: - question properties: question: type: string minLength: 1 description: Research question to ask the study. sourcePolicy: type: string enum: - auto - knowledge_only default: auto description: knowledge_only forbids live/request sources, requires each Mind's processed knowledge, and fails closed when retrieval is empty. historyMode: type: string enum: - last5 - followup_only - none default: none description: How much of each Mind's own prior answers this question carries. Defaults to none. Use last5 when a respondent's coherence across items is the deliverable. audienceIds: type: array description: Optional subset of attached audience UUIDs to ask. Defaults to all audiences on the study. items: type: string format: uuid attachments: type: array description: Files or images to process once and include as context for every Mind in the Study. items: $ref: '#/components/schemas/StudyAttachment' links: type: array description: Web links to fetch and summarize for context. items: $ref: '#/components/schemas/StudyContextLink' keywords: type: array description: Keyword/source pairs to fetch and summarize for context. items: $ref: '#/components/schemas/StudyKeywordContext' model: type: string description: Optional per-request model override. Must be sent together with `provider`. provider: type: string enum: - openai - anthropic - google description: Provider for the model override. Must be sent together with `model`. disableQuestionClassifier: type: boolean default: false description: Skip automatic scale/categorical/multiselect/qualitative classification. responseMode: type: string enum: - stream - queued default: stream description: Use queued to persist the question and return immediately while durable workers generate the answers. responseForm: type: string enum: - concise - standard - expanded description: 'How long and how shaped each answer should be, for qualitative questions: `concise` one short message (5-20 words), `standard` 1-3 sentences (25-90 words), `expanded` 2-5 sentences (70-180 words). Omit to let the question decide, which is the existing behaviour. An authored form outranks the phrasing of the question, so a fixed instrument keeps its exact wording. Ignored for scale, categorical and multiselect questions, which are shaped by their answer space.' clientRequestId: type: string format: uuid description: Optional idempotency key for queued submissions. StudyKeywordContext: type: object properties: label: type: string description: Keyword or topic label. url: type: string description: Optional source URL for the keyword. id: type: string StudyQuestionClassification: type: object required: - type properties: type: type: string enum: - scale - categorical - multiselect - qualitative scaleRange: type: array minItems: 2 maxItems: 2 items: type: number options: type: array items: type: string responseMode: type: string enum: - everyday - standard_qualitative - deliberative_values - scale - categorical - factual_research description: Answer-depth and grounding policy, orthogonal to the structured response type. StudyDetail: type: object required: - id - name - flowMode - createdAt - updatedAt - isLinkSharingEnabled - publicShareId - audiences - messages properties: id: type: string format: uuid name: type: string studyMode: type: string enum: - study createdAt: type: string format: date-time updatedAt: type: string format: date-time isLinkSharingEnabled: type: boolean publicShareId: type: - string - 'null' format: uuid audiences: type: array items: $ref: '#/components/schemas/StudyAudience' messages: type: array items: $ref: '#/components/schemas/StudyMessage' StudyOutputAnswer: type: object required: - value - persona - message properties: value: type: string rawValue: type: string persona: type: string discipline: type: - string - 'null' message: type: string imageUrl: type: - string - 'null' reliabilityScore: type: integer minimum: 0 maximum: 100 citationSources: type: array description: Claim-level sources referenced by zero-based [N] markers in message. items: $ref: '#/components/schemas/StudyCitationSource' citationProvenance: $ref: '#/components/schemas/StudyCitationProvenance' answerProvenance: $ref: '#/components/schemas/StudyAnswerProvenance' StudyCategoryCodebookEntry: type: object required: - label - originalLabels - count properties: label: type: string originalLabels: type: array items: type: string count: type: integer minimum: 0 StudyExportStatusResponse: type: object required: - data properties: data: type: object required: - status properties: status: type: string enum: - idle - queued - processing - completed - failed progress: type: number minimum: 0 maximum: 100 downloadUrl: type: string format: uri error: type: string errorCode: type: string enum: - EXPORT_FAILED generatedAt: type: - string - 'null' format: date-time filename: type: string mimeType: type: string kind: type: string enum: - executive_brief - full_report - raw_data format: type: string enum: - pdf - html - png - md - docx - pptx - csv - xls - sav sourceVersion: type: string StudySummary: type: object required: - id - name - flowMode - createdAt - updatedAt - messageCount - audiences properties: id: type: string format: uuid name: type: string studyMode: type: string enum: - study description: Canonical Study resource discriminator. createdAt: type: string format: date-time updatedAt: type: string format: date-time messageCount: type: integer isLinkSharingEnabled: type: boolean publicShareId: type: - string - 'null' format: uuid audiences: type: array items: type: object required: - id - name - mindCount - minds properties: id: type: string format: uuid name: type: string mindCount: type: integer minds: type: array items: type: object required: - id - name properties: id: type: string format: uuid name: type: string discipline: type: - string - 'null' profileImageUrl: type: - string - 'null' format: uri StudyCreated: type: object required: - id - name - flowMode - createdAt - isLinkSharingEnabled - publicShareId - audiences properties: id: type: string format: uuid name: type: string studyMode: type: string enum: - study createdAt: type: string format: date-time isLinkSharingEnabled: type: boolean publicShareId: type: - string - 'null' format: uuid audiences: type: array items: $ref: '#/components/schemas/StudyAudience' StudyAskSseEvent: oneOf: - $ref: '#/components/schemas/StudyAskStartEvent' - $ref: '#/components/schemas/StudyAskClassificationEvent' - $ref: '#/components/schemas/StudyAskAnswerEvent' - $ref: '#/components/schemas/StudyAskAggregatingEvent' - $ref: '#/components/schemas/StudyAskResultEvent' - $ref: '#/components/schemas/StudyAskDoneEvent' StudyAttachment: type: object properties: url: type: string description: External URL for the uploaded or remote file. path: type: string description: Storage path for an uploaded file. name: type: string type: type: string description: MIME type when known. StudyCitationProvenance: type: object required: - mode - status - recordedAt - verifier properties: mode: type: string enum: - generation - retroactive status: type: string enum: - attributed - verified - partial - unavailable recordedAt: type: string format: date-time verifier: type: string enum: - study-citations-v1 reason: type: string enum: - no_evidence - no_claims - timeout - error description: 'Only when status is unavailable: why no sources could be attributed.' StudyAskAnswerEvent: type: object required: - type - mindId - mindName - audienceId - audienceName - answer properties: type: type: string enum: - answer mindId: type: string format: uuid mindName: type: string discipline: type: - string - 'null' profileImageUrl: type: - string - 'null' audienceId: type: string format: uuid audienceName: type: string answer: type: string securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: 'Personal API key. Format: `Bearer minds_…_key`. Create one at https://getminds.ai/settings/api-keys.'