---
title: "Studies API"
description: "Create Studies, run cohesive multi-question blocks with Audiences, inspect results, and export artifacts through the Minds v1 API."
---

# Studies API

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

```bash
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.

1. `POST /studies/{studyId}/research-plans/preview` creates or revises a versioned plan containing the cohesive question modules.
2. Review the exact plan and answer any confirmation questions.
3. `POST /studies/{studyId}/research-runs` confirms one precise revision and queues all questions together.
4. `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

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Path
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

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

## 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](/api/reference), the [agent integration guide](/api/agents), and the live [OpenAPI document](/api/openapi).