Audiences API
Create, ground, manage, and export reusable Audiences of Minds, then attach them to cohesive research Studies through the Minds v1 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
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}:
| Field | Effect |
|---|---|
isSharedWithTeam | 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. |
isPublic | Anyone can open the Audience and its Minds (marketplace listing). |
isLinkSharingEnabled | Anyone with the link can open the Audience. Set at creation; not editable through PUT. |
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
| Method | Path | Purpose |
|---|---|---|
GET | /audiences | List visible Audiences |
POST | /audiences | Create an Audience from existing Mind IDs |
GET | /audiences/{audienceId} | Read members, access, grounding, and Formations |
PUT | /audiences/{audienceId} | Update supported fields and sharing settings |
DELETE | /audiences/{audienceId} | Delete a confirmed Audience |
POST | /audiences/{audienceId}/members | Add a Mind |
DELETE | /audiences/{audienceId}/members/{mindId} | Remove a Mind |
GET | /audiences/{audienceId}/progress | Read creation and training progress |
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:
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 and the live OpenAPI document.
