---
title: "Audiences API"
description: "Create, ground, manage, and export reusable Audiences of Minds, then attach them to cohesive research Studies through the Minds v1 API."
---

# Audiences API

An **Audience** is a reusable collection of Minds. Build it once, ground it with research sources when needed, and attach it to one or more Studies.

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

## Create an Audience

```bash
curl -X POST "https://api.getminds.ai/v1/audiences" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "German SaaS buyers",
    "mindIds": ["mind-id-1", "mind-id-2"]
  }'
```

Audiences are private by default. Set `isLinkSharingEnabled: true` only when the user explicitly requests a public link.

## Sharing and access

An Audience carries its own sharing settings, editable through `PUT /audiences/{audienceId}`:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Effect
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        isSharedWithTeam
      </code>
    </td>
    
    <td>
      Every member of the owner's team can open the Audience and read and chat with every Mind in it, even when those Minds are not shared individually.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      Anyone can open the Audience and its Minds (marketplace listing).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLinkSharingEnabled
      </code>
    </td>
    
    <td>
      Anyone with the link can open the Audience. Set at creation; not editable through <code>
        PUT
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Explicit Audience members get the same read access as team members. Access gained through an Audience is read-and-chat only: it never grants edit or delete rights on the Minds inside. This is how curated Minds are typically delivered to a partner team — share one Audience with the team instead of sharing each Mind, and let the team discover the Minds through `GET /minds/library`.

## 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>
        /audiences
      </code>
    </td>
    
    <td>
      List visible Audiences
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /audiences
      </code>
    </td>
    
    <td>
      Create an Audience from existing Mind IDs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /audiences/{audienceId}
      </code>
    </td>
    
    <td>
      Read members, access, grounding, and Formations
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
    </td>
    
    <td>
      <code>
        /audiences/{audienceId}
      </code>
    </td>
    
    <td>
      Update supported fields and sharing settings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /audiences/{audienceId}
      </code>
    </td>
    
    <td>
      Delete a confirmed Audience
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /audiences/{audienceId}/members
      </code>
    </td>
    
    <td>
      Add a Mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE
      </code>
    </td>
    
    <td>
      <code>
        /audiences/{audienceId}/members/{mindId}
      </code>
    </td>
    
    <td>
      Remove a Mind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /audiences/{audienceId}/progress
      </code>
    </td>
    
    <td>
      Read creation and training progress
    </td>
  </tr>
</tbody>
</table>

## Create a grounded Audience from a brief

`POST /audiences/from-brief` accepts a research brief plus source files or URLs and creates a grounded synthetic Audience. PDF, DOCX, CSV, XLS, and XLSX inputs enter the same classification and extraction pipeline used by the webapp.

For respondent spreadsheets, preview segmentation first:

```text
POST /audiences/from-brief/segmentation-preview
```

The preview distinguishes completed respondent data from screeners and questionnaire programming grids. It excludes identifiers, weights, free text, and derived statistics from representative cohort allocation by default, and preserves the valid base for conditional or multi-select questions.

## Formations

A **Formation** is a persisted segmentation inside one Audience. Use `/audiences/{audienceId}/formations` to list, create, preview, recompute, or delete Formations without creating another Audience.

## Exports

Start a branded Audience brief with `POST /audiences/{audienceId}/export`, poll `/export-status`, then download from `/export-download` when complete.

## Compatibility

The former `/groups` routes remain callable during the migration window. They return `Deprecation: true` and a `Link` header naming the canonical `/audiences` successor. New integrations should use Audience paths and terminology exclusively.

See the exhaustive [v1 endpoint reference](/api/reference) and the live [OpenAPI document](/api/openapi).