Studies API | Minds

A Study is the research workspace. It contains one or more Audiences, questions, evidence, results, analysis, and exports.

Base URL: https://api.getminds.ai/v1

Create a Study

curl -X POST "https://api.getminds.ai/v1/studies" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch positioning",
    "audienceIds": ["audience-id-1", "audience-id-2"]
  }'

Canonical Study responses use studyMode: "study" and an audiences collection. Inline audienceConfigs can create and attach Audiences atomically; if any inline Audience fails, the entire composite creation is rolled back.

Run questions as a cohesive block

For a broader objective or more than one question, use the guided lifecycle. Do not submit a questionnaire one question at a time.

POST /studies/{studyId}/research-plans/preview creates or revises a versioned plan containing the cohesive question modules.
Review the exact plan and answer any confirmation questions.
POST /studies/{studyId}/research-runs confirms one precise revision and queues all questions together.
GET /studies/{studyId}/research-runs/{runId} returns durable progress, response contracts, artifacts, calculations, and next actions.

The planner may use multiple named modules or sections when that improves the research design. Each module should contain related questions with a clear purpose; the executor preserves the reviewed order and shared context.

Use POST /studies/{studyId}/ask only for a genuinely standalone question. Use POST /studies/{studyId}/runs for a durable direct run that needs polling, replay, cancellation, or knowledge-only source policy.

A research run can finish collecting with status: "partial" when a question or respondent answer is missing. Stop polling this terminal state and explain the gap; do not describe it as complete. progress.pct measures settled questions, not respondent coverage. New question outputs retain outputData.responseCoverage with expected, received, and missing Audience/Mind memberships. progress.partial counts questions with recorded incomplete coverage. Missing coverage on older artifacts is unknown, not proof that everyone answered. Keep valid raw answers and their outcomes unchanged; review missing work before starting a separate retry.

Core endpoints

Method	Path	Purpose
`GET`	`/studies`	List Studies
`POST`	`/studies`	Create a Study from Audiences
`GET`	`/studies/{studyId}`	Read Study composition and history
`DELETE`	`/studies/{studyId}`	Delete a confirmed Study
`POST`	`/studies/{studyId}/ask`	Ask one standalone question
`POST`	`/studies/{studyId}/runs`	Start a durable direct run
`GET`	`/studies/{studyId}/analytics`	Compute categorical, scale, multiselect, and qualitative analytics
`GET`	`/studies/{studyId}/summary`	Read the persisted semantic summary
`POST`	`/studies/{studyId}/summary`	Generate or refresh the semantic summary
`PUT`	`/studies/{studyId}/sharing`	Change public link sharing after explicit approval

Exports

Start an artifact with POST /studies/{studyId}/export, poll /export-status, then download from /export-download. Supported outputs include the full report, executive summary, raw data, and presentation formats exposed by the export endpoint.

Compatibility

The former /panels routes remain callable during the migration window. They return Deprecation: true and a Link header naming the canonical /studies successor. Deprecated routes retain legacy wire fields such as groupIds, groups, and flowMode: "panel"; new integrations should use audienceIds, audiences, and studyMode: "study".

See the exhaustive v1 endpoint reference, the agent integration guide, and the live OpenAPI document.