---
title: "Minds v1 API Endpoint Catalog"
description: "Complete customer-facing catalog of Minds v1 REST endpoints, response modes, and corresponding MCP capabilities."
---

# Minds v1 API Endpoint Catalog

This catalog lists the complete customer-facing v1 route surface. Use it with the live [OpenAPI 3.1 document](/api/openapi) for schemas and the [agent integration guide](/api/agents) for safe orchestration patterns.

## Conventions

- Apex base URL: `https://getminds.ai/api/v1`
- API-subdomain base URL: `https://api.getminds.ai/v1`
- Authentication: `Authorization: Bearer minds_…`
- JSON requests: `Content-Type: application/json`
- Most JSON responses use `{ "data": ... }`; validation and access failures use the shared error envelope documented under [Errors & Limits](/api/errors).
- `{id}`, `{mindId}`, `{studyId}`, and similar tokens are path parameters, not literal strings.
- `DELETE` operations are destructive. Confirm the exact resource identifiers before calling them.
- MCP mappings identify the equivalent capability. An MCP tool may compose more than one v1 request or expose several routes through an `action` parameter.

## Meta, identity, and credentials

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/openapi.json
      </code>
    </td>
    
    <td>
      Return the public OpenAPI 3.1 document; authentication is not required
    </td>
    
    <td>
      MCP publishes protocol-native <code>
        tools/list
      </code>
      
       discovery
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/auth/me
      </code>
    </td>
    
    <td>
      Read the authenticated account identity and plan context
    </td>
    
    <td>
      Intentionally transport context, not an MCP research tool
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/api-keys
      </code>
    </td>
    
    <td>
      List API-key metadata; secret values are never returned again
    </td>
    
    <td>
      Intentionally excluded from MCP
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/api-keys
      </code>
    </td>
    
    <td>
      Mint an API key and return its secret once
    </td>
    
    <td>
      Intentionally excluded from MCP
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/api-keys/{keyId}
      </code>
    </td>
    
    <td>
      Revoke an API key
    </td>
    
    <td>
      Intentionally excluded from MCP
    </td>
  </tr>
</tbody>
</table>

MCP sessions cannot mint, rotate, or revoke their own bearer credentials. Manage credentials only through authenticated account settings or the REST endpoints above.

## Minds

The historical API resource name for a Mind is `spark`.

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds
      </code>
    </td>
    
    <td>
      List owned Minds with pagination and filters
    </td>
    
    <td>
      <code>
        list_minds
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds
      </code>
    </td>
    
    <td>
      Create and queue training for a Mind
    </td>
    
    <td>
      <code>
        create_mind
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds
      </code>
    </td>
    
    <td>
      Batch-delete confirmed Minds through canonical cleanup
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "delete_many"
      </code>
      
       (1–100 IDs per tool call)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/library
      </code>
    </td>
    
    <td>
      Read the first-party owned/shared library projection
    </td>
    
    <td>
      <code>
        list_minds
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}
      </code>
    </td>
    
    <td>
      Read one visible Mind
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "get"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}
      </code>
    </td>
    
    <td>
      Update editable Mind fields and sharing configuration
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "update"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}
      </code>
    </td>
    
    <td>
      Delete one confirmed Mind and associated resources
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/training
      </code>
    </td>
    
    <td>
      Read training status and progress
    </td>
    
    <td>
      <code>
        get_mind_status
      </code>
      
       or <code>
        manage_mind
      </code>
      
       with <code>
        action: "get_training"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/retrain
      </code>
    </td>
    
    <td>
      Queue retraining and rebuild the complete stored knowledge index before ready
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "retrain"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/regenerate-image
      </code>
    </td>
    
    <td>
      Regenerate the Mind profile image
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "regenerate_image"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/regenerate-prompt
      </code>
    </td>
    
    <td>
      Regenerate the system prompt from current knowledge
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "regenerate_prompt"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/regenerate-embeddings
      </code>
    </td>
    
    <td>
      Queue a fresh vector rebuild for every stored knowledge item
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "regenerate_embeddings"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/patterns
      </code>
    </td>
    
    <td>
      Read raw Mind patterns when access permits
    </td>
    
    <td>
      <code>
        manage_mind
      </code>
      
       with <code>
        action: "get_patterns"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/completion
      </code>
    </td>
    
    <td>
      Run a stateless completion with one Mind
    </td>
    
    <td>
      <code>
        chat_with_mind
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/export
      </code>
    </td>
    
    <td>
      Start or return a Mind profile export
    </td>
    
    <td>
      <code>
        export_mind
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/export-status
      </code>
    </td>
    
    <td>
      Poll an asynchronous Mind export
    </td>
    
    <td>
      <code>
        export_mind
      </code>
      
       returns status information
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/export-download
      </code>
    </td>
    
    <td>
      Download a completed Mind export
    </td>
    
    <td>
      <code>
        export_mind
      </code>
      
       returns the artifact or link
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/user/shareable-sparks
      </code>
    </td>
    
    <td>
      List Minds eligible for a sharing picker
    </td>
    
    <td>
      <code>
        list_minds
      </code>
    </td>
  </tr>
</tbody>
</table>

Batch deletion accepts:

```json
{
  "mindIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}
```

The response reports `deleted`, `notFound`, and `failed` IDs independently so one cleanup failure does not conceal the rest of the batch.

## Mind knowledge

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge
      </code>
    </td>
    
    <td>
      List knowledge items
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "list"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge
      </code>
    </td>
    
    <td>
      Add a link, keyword search, multipart file, or URL-referenced file
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "add"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge/{itemId}
      </code>
    </td>
    
    <td>
      Update description, watch state, or supported metadata
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "update"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge/{itemId}
      </code>
    </td>
    
    <td>
      Delete a knowledge item and associated stored artifact
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge/{itemId}/status
      </code>
    </td>
    
    <td>
      Poll knowledge processing
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "status"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge/enrich
      </code>
    </td>
    
    <td>
      Convenience keyword-enrichment operation
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "enrich"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/minds/{mindId}/knowledge/patterns
      </code>
    </td>
    
    <td>
      Read knowledge patterns by framework
    </td>
    
    <td>
      <code>
        manage_mind_knowledge
      </code>
      
       with <code>
        action: "patterns"
      </code>
    </td>
  </tr>
</tbody>
</table>

For agent-originated files, pass a public, short-lived signed, or Minds workspace-upload URL rather than base64 content:

```json
{
  "file": {
    "name": "research-brief.pdf",
    "url": "https://signed.example/research-brief.pdf",
    "type": "application/pdf"
  },
  "description": "Primary customer research brief",
  "regeneratePrompt": true
}
```

Remote retrieval is SSRF-guarded, limited to 50 MB, and time-bounded. Multipart and URL-referenced files enter the same storage and processing queue.

Canonical product resources are **Audiences** and **Studies**. The former `/api/v1/groups` and `/api/v1/panels` paths remain callable during the compatibility window, but return `Deprecation: true` and a `Link` header pointing to the canonical successor. New integrations should not use the legacy paths or names.

## Audiences and grounding

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences
      </code>
    </td>
    
    <td>
      List visible Audiences
    </td>
    
    <td>
      <code>
        list_audiences
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences
      </code>
    </td>
    
    <td>
      Create an Audience from explicit Mind IDs
    </td>
    
    <td>
      <code>
        create_audience
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/library
      </code>
    </td>
    
    <td>
      Read the first-party owned/followed/shared library projection
    </td>
    
    <td>
      <code>
        list_audiences
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}
      </code>
    </td>
    
    <td>
      Read members, access, grounding, and Formations
    </td>
    
    <td>
      <code>
        get_audience
      </code>
      
       or <code>
        manage_audience
      </code>
      
       with <code>
        action: "get"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}
      </code>
    </td>
    
    <td>
      Update supported Audience fields and sharing configuration
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "update"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}
      </code>
    </td>
    
    <td>
      Delete a confirmed Audience
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/members
      </code>
    </td>
    
    <td>
      Add one Mind to an Audience
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "add_member"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/members/{mindId}
      </code>
    </td>
    
    <td>
      Remove one Mind from an Audience
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "remove_member"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/follow
      </code>
    </td>
    
    <td>
      Follow/save a visible public Audience
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "follow"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/follow
      </code>
    </td>
    
    <td>
      Unfollow a saved Audience
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "unfollow"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/progress
      </code>
    </td>
    
    <td>
      Read settled creation progress
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "get_progress"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/active-progress
      </code>
    </td>
    
    <td>
      Read active Audience/Mind build progress for the UI
    </td>
    
    <td>
      Use per-Audience or per-Mind MCP status tools
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/lifecycle/stream
      </code>
    </td>
    
    <td>
      Stream user-scoped invalidation hints; clients re-read durable state after each event
    </td>
    
    <td>
      MCP uses durable status reads instead of a browser SSE subscription
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/recalibrate
      </code>
    </td>
    
    <td>
      Replace stored grounding with refreshed authoritative research
    </td>
    
    <td>
      <code>
        recalibrate_audience
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/regenerate-images
      </code>
    </td>
    
    <td>
      Regenerate Audience member images with optional limits/dry run
    </td>
    
    <td>
      <code>
        manage_audience
      </code>
      
       with <code>
        action: "regenerate_images"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/from-brief
      </code>
    </td>
    
    <td>
      Create a grounded synthetic audience from a brief and sources
    </td>
    
    <td>
      <code>
        create_audience_from_brief
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/from-brief/jobs/{jobId}
      </code>
    </td>
    
    <td>
      Poll an asynchronous from-brief Audience creation operation
    </td>
    
    <td>
      Polled automatically by <code>
        create_audience_from_brief
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/from-brief/segmentation-preview
      </code>
    </td>
    
    <td>
      Inspect respondent-data variables before representative cohort creation
    </td>
    
    <td>
      <code>
        preview_audience_dataset_segmentation
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/allocation-preview
      </code>
    </td>
    
    <td>
      Non-mutating deterministic cohort-allocation preview
    </td>
    
    <td>
      <code>
        create_audience_from_brief
      </code>
      
       cohort-allocation workflow
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/export
      </code>
    </td>
    
    <td>
      Start or return a branded Audience brief export
    </td>
    
    <td>
      <code>
        export_audience
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/export-status
      </code>
    </td>
    
    <td>
      Poll an asynchronous Audience export
    </td>
    
    <td>
      <code>
        export_audience
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/export-download
      </code>
    </td>
    
    <td>
      Download a completed Audience export
    </td>
    
    <td>
      <code>
        export_audience
      </code>
      
       returns the artifact
    </td>
  </tr>
</tbody>
</table>

Audiences and Studies are private by default. Set `isLinkSharingEnabled: true` only when the user explicitly requests a public link; doing so can make persisted grounding and attached research context readable through the shared surface.

## Audience Formations

A Formation is a persisted segmentation of one Audience into defined subgroups.

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/formations
      </code>
    </td>
    
    <td>
      List Formations
    </td>
    
    <td>
      <code>
        list_formations
      </code>
      
       or <code>
        manage_formation
      </code>
      
       with <code>
        action: "list"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/formations
      </code>
    </td>
    
    <td>
      Create and compute a Formation
    </td>
    
    <td>
      <code>
        manage_formation
      </code>
      
       with <code>
        action: "create"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/formations/preview
      </code>
    </td>
    
    <td>
      Generate a non-persisted segmentation hypothesis
    </td>
    
    <td>
      <code>
        manage_formation
      </code>
      
       with <code>
        action: "preview"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/formations/{formationId}
      </code>
    </td>
    
    <td>
      Read one Formation
    </td>
    
    <td>
      <code>
        manage_formation
      </code>
      
       with <code>
        action: "get"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/formations/{formationId}
      </code>
    </td>
    
    <td>
      Delete a confirmed Formation
    </td>
    
    <td>
      <code>
        manage_formation
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/audiences/{id}/formations/{formationId}/recompute
      </code>
    </td>
    
    <td>
      Recompute member assignments
    </td>
    
    <td>
      <code>
        manage_formation
      </code>
      
       with <code>
        action: "recompute"
      </code>
    </td>
  </tr>
</tbody>
</table>

The preview endpoint content-negotiates. Use `Accept: application/x-ndjson` for incremental browser progress or `Accept: application/json` for a single agent-friendly hypothesis. Both representations use the same generator.

## Studies, analytics, and exports

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies
      </code>
    </td>
    
    <td>
      List Studies
    </td>
    
    <td>
      <code>
        list_studies
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies
      </code>
    </td>
    
    <td>
      Create a Study from existing Audiences or inline <code>
        audienceConfigs
      </code>
    </td>
    
    <td>
      <code>
        create_study
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}
      </code>
    </td>
    
    <td>
      Read Study composition and history
    </td>
    
    <td>
      <code>
        get_study_status
      </code>
      
       or <code>
        manage_study
      </code>
      
       with <code>
        action: "get"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}
      </code>
    </td>
    
    <td>
      Delete a confirmed Study
    </td>
    
    <td>
      <code>
        manage_study
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/ask
      </code>
    </td>
    
    <td>
      Submit one direct question; supports SSE and queued modes
    </td>
    
    <td>
      <code>
        ask_study
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/analytics
      </code>
    </td>
    
    <td>
      Compute scale, categorical, and qualitative analytics
    </td>
    
    <td>
      <code>
        get_study_analytics
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/invitations
      </code>
    </td>
    
    <td>
      Invite Study collaborators without exposing invitation tokens
    </td>
    
    <td>
      <code>
        manage_study
      </code>
      
       with <code>
        action: "invite"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/export
      </code>
    </td>
    
    <td>
      Start an export in a supported format
    </td>
    
    <td>
      <code>
        export_study
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/export-status
      </code>
    </td>
    
    <td>
      Poll export status
    </td>
    
    <td>
      <code>
        export_study
      </code>
      
       / <code>
        get_study_status
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/export-download
      </code>
    </td>
    
    <td>
      Download a completed export
    </td>
    
    <td>
      <code>
        export_study
      </code>
      
       returns an artifact or link
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/heatmaps/{messageId}/export
      </code>
    </td>
    
    <td>
      Start or return a website-heatmap ZIP export
    </td>
    
    <td>
      <code>
        export_heatmap
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/heatmaps/{messageId}/export-status
      </code>
    </td>
    
    <td>
      Poll a website-heatmap ZIP export
    </td>
    
    <td>
      <code>
        export_heatmap
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/heatmaps/{messageId}/export-download
      </code>
    </td>
    
    <td>
      Download a completed website-heatmap ZIP
    </td>
    
    <td>
      <code>
        export_heatmap
      </code>
      
       returns a signed URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/summary
      </code>
    </td>
    
    <td>
      Read the persisted flexible semantic summary
    </td>
    
    <td>
      <code>
        get_study_summary
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/summary
      </code>
    </td>
    
    <td>
      Generate or refresh the semantic summary
    </td>
    
    <td>
      <code>
        get_study_summary
      </code>
      
       with <code>
        refresh: true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/sharing
      </code>
    </td>
    
    <td>
      Enable or disable the public Study link
    </td>
    
    <td>
      <code>
        manage_study
      </code>
      
       with <code>
        action: "set_link_sharing"
      </code>
    </td>
  </tr>
</tbody>
</table>

Composite creation through `audienceConfigs` is atomic: if any inline Audience fails, the operation rolls back the Study and Audiences created by that request. The legacy `groupIds` and `groupConfigs` request fields remain accepted on deprecated routes; canonical Study routes use `audienceIds` and `audienceConfigs` and return `studyMode: "study"` with an `audiences` collection.

## Guided Studies and durable runs

For any broader objective or more than one question, plan and execute one cohesive multi-question block. Related questions should be organized into named modules or sections and run together; reserve the direct ask endpoint for a genuinely standalone question.

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

<tbody>
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/research-plans/preview
      </code>
    </td>
    
    <td>
      Create or revise a versioned research-plan draft
    </td>
    
    <td>
      <code>
        plan_study_questions
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/research-runs
      </code>
    </td>
    
    <td>
      Confirm and run the exact reviewed plan revision
    </td>
    
    <td>
      <code>
        run_study_questions
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/research-runs/{runId}
      </code>
    </td>
    
    <td>
      Poll Study progress, methods, artifacts, and calculations
    </td>
    
    <td>
      <code>
        get_study_run
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/runs
      </code>
    </td>
    
    <td>
      Start a durable direct Study run
    </td>
    
    <td>
      <code>
        ask_study
      </code>
      
       for direct questions or <code>
        run_study_questions
      </code>
      
       for planned research
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/studies/{studyId}/runs
      </code>
    </td>
    
    <td>
      List durable runs for a Study
    </td>
    
    <td>
      <code>
        get_study_status
      </code>
      
       / <code>
        get_study_run
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/runs/{runId}
      </code>
    </td>
    
    <td>
      Read durable run status
    </td>
    
    <td>
      <code>
        get_study_status
      </code>
      
       / <code>
        get_study_run
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/runs/{runId}/events
      </code>
    </td>
    
    <td>
      Read ordered run events using <code>
        after
      </code>
      
       and <code>
        limit
      </code>
      
       cursors
    </td>
    
    <td>
      MCP status tools return durable progress
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/runs/{runId}/cancel
      </code>
    </td>
    
    <td>
      Cancel a running durable job
    </td>
    
    <td>
      No dedicated curated MCP tool
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/research-methods
      </code>
    </td>
    
    <td>
      List versioned methods, execution support, requirements, and fallbacks
    </td>
    
    <td>
      <code>
        list_research_methods
      </code>
    </td>
  </tr>
</tbody>
</table>

Creating a plan does not start research. Start only after the user explicitly confirms the exact returned revision. `executable: false` means a represented method is informational or planned, not runnable.

## Durable Study drafts

These endpoints persist the same resumable planner state used by the first-party Study sidebar.

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

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/study-drafts
      </code>
    </td>
    
    <td>
      List owned resumable drafts
    </td>
    
    <td>
      <code>
        list_study_drafts
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/study-drafts
      </code>
    </td>
    
    <td>
      Create a durable draft
    </td>
    
    <td>
      <code>
        save_study_draft
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/study-drafts/{id}
      </code>
    </td>
    
    <td>
      Read one complete draft
    </td>
    
    <td>
      <code>
        list_study_drafts
      </code>
      
       with <code>
        draftId
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PATCH
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/study-drafts/{id}
      </code>
    </td>
    
    <td>
      Revise a draft using optimistic concurrency
    </td>
    
    <td>
      <code>
        save_study_draft
      </code>
      
       with <code>
        draftId
      </code>
      
       and <code>
        expectedRevision
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/study-drafts/{id}
      </code>
    </td>
    
    <td>
      Delete a confirmed draft
    </td>
    
    <td>
      <code>
        manage_study_draft
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/study-drafts/{id}/consume
      </code>
    </td>
    
    <td>
      Mark a precise revision consumed and optionally attach it to a Study
    </td>
    
    <td>
      <code>
        manage_study_draft
      </code>
      
       with <code>
        action: "consume"
      </code>
    </td>
  </tr>
</tbody>
</table>

Always send the exact `expectedRevision` returned by the last read. A stale revision is rejected rather than overwriting newer planning state.

## Stateful chats

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

<tbody>
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/chats
      </code>
    </td>
    
    <td>
      Create a stateful single-Mind, multi-Mind, or Audience-backed chat
    </td>
    
    <td>
      <code>
        manage_chat
      </code>
      
       with <code>
        action: "create"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/chats/{chatId}/messages
      </code>
    </td>
    
    <td>
      Append a user/system message and receive the next response
    </td>
    
    <td>
      <code>
        manage_chat
      </code>
      
       with <code>
        action: "send_message"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /api/v1/chats/{chatId}
      </code>
    </td>
    
    <td>
      Delete a confirmed chat and its persisted history
    </td>
    
    <td>
      <code>
        manage_chat
      </code>
      
       with <code>
        action: "delete"
      </code>
    </td>
  </tr>
</tbody>
</table>

For a one-off Mind request without server-managed history, use the stateless completion endpoint instead.

## Choosing the next reference

- Request and response examples: [Minds](/api/minds), [Audiences](/api/audiences), [Studies](/api/studies), [Knowledge](/api/knowledge), and [Chat](/api/chat)
- Authentication and key rotation: [Authentication](/api/authentication)
- Errors, plan limits, and retry policy: [Errors & Limits](/api/errors)
- Autonomous integrations: [API guide for agents](/api/agents)
- Tool-native integrations: [MCP tools reference](/mcp/tools)