# Minds overview :guide-intro-video Minds is a synthetic market research platform built around three objects: - **Minds** — individual synthetic respondents for in-depth interviews - **Audiences** — reusable synthetic samples made from multiple Minds - **Studies** — saved research workspaces for questions, stimuli, responses, and results ## Research methods A Study can contain: - an **in-depth interview** with one Mind - **qualitative exploration at scale** with an Audience - a **questionnaire** with directional quantitative readouts - a **concept, message, pricing, or visual-asset test** - a **segment comparison** across multiple Audiences - a **mixed-method Study** combining these approaches Synthetic results are directional evidence. Their strength depends on Audience definition, grounding, question design, and the available validation evidence; they are not automatically population estimates. ## Get started 1. Create a **Mind** or choose an existing one. 2. Create an **Audience** when you want to reuse several perspectives. 3. Start a **Study** and choose **Quick** or **Custom** setup. 4. Select the research method that fits the decision. Interviews give you depth. Audiences give you breadth. Studies keep the evidence for a decision together. ## Continue reading - [Minds](https://getminds.ai/guide/minds) - [Studies](https://getminds.ai/guide/studies) - [Audiences and methods](https://getminds.ai/guide/audiences) - [Integrations](https://getminds.ai/guide/integrations) # API Overview The Minds v1 API exposes supported programmatic workflows for Minds, Audiences, Studies, knowledge, chat, analytics, and exports. ## Getting Started The Minds API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ### Base URL **Production:** `https://getminds.ai/api/v1` (canonical) or `https://api.getminds.ai/v1` (alias) **Local Development:** `http://localhost:3000/api/v1` Both production base URLs serve the same endpoints with the same authentication. `https://getminds.ai/api/v1` is the canonical form used throughout these docs and by the OpenAPI document; the `api.getminds.ai` alias maps `/v1/*` onto the same routes for integrations that prefer a dedicated API host. ### Authentication All research endpoints require authentication via API key. The OpenAPI documents are intentionally public so clients can discover the authentication contract. Generate and manage keys in [Settings → API Keys](https://getminds.ai/settings/api-keys). Include your API key in the `Authorization` header: ```bash Authorization: Bearer minds_your_api_key_here ``` ### OpenAPI Spec A machine-readable OpenAPI 3.1.0 spec is published at [`/_openapi.json`](https://getminds.ai/_openapi.json). Use it for typed client generation and combine it with the [complete endpoint catalog](https://getminds.ai/docs/api/reference) for v1 routes whose detailed OpenAPI schemas are still being expanded. Agents should also read the [API integration guide for agents](https://getminds.ai/docs/api/agents). ### Content Type All requests that send data should include the `Content-Type` header: ```bash Content-Type: application/json ``` For file uploads, use: ```bash Content-Type: multipart/form-data ``` ## Capability overview This overview highlights the primary workflows. The [v1 endpoint catalog](https://getminds.ai/docs/api/reference) lists every customer-facing route, including lifecycle, progress, Formation, durable-run, Study-draft, analytics, and export helpers. ### Minds Create and manage AI minds (agents) with custom configurations. - `GET /api/v1/minds` - List the Minds you own - `GET /api/v1/minds/library` - List every Mind you can open: owned, shared with you or your team, or reached through an Audience or Study (use this for partner or team deliveries) - `GET /api/v1/minds/{mindId}` - Get Mind details - `POST /api/v1/minds` - Create a new Mind - `PUT /api/v1/minds/{mindId}` - Update a Mind - `DELETE /api/v1/minds/{mindId}` - Delete a Mind - `DELETE /api/v1/minds` - Batch-delete confirmed Minds with the same file and telephony cleanup as single delete - `POST /api/v1/minds/{mindId}/regenerate-prompt` - Regenerate system prompt from knowledge - `GET /api/v1/minds/{mindId}/patterns` - Get raw thinking patterns for a Mind ### Audiences Create and manage reusable Audiences used by Studies. - `GET /api/v1/audiences` - List visible Audiences - `GET /api/v1/audiences/library` - List the first-party owned and shared Audience library projection - `POST /api/v1/audiences` - Create an Audience - `GET /api/v1/audiences/{audienceId}` - Get Audience details - `PUT /api/v1/audiences/{audienceId}` - Update an Audience - `DELETE /api/v1/audiences/{audienceId}` - Delete an Audience - `POST /api/v1/audiences/{audienceId}/follow` - Save a public Audience - `DELETE /api/v1/audiences/{audienceId}/follow` - Remove a saved public Audience - `GET /api/v1/audiences/{audienceId}/progress` - Read settled Audience build progress - `POST /api/v1/audiences/{audienceId}/formations/preview` - Preview a Formation as NDJSON or JSON - `POST /api/v1/audiences/{audienceId}/validations` - Validate an Audience against real, published surveys - `GET /api/v1/audiences/{audienceId}/validations` - List an Audience's validations and its overall validity - `GET /api/v1/audiences/{audienceId}/validations/batches/{batchId}` - Read one validation's status and results ### Knowledge Manage knowledge for your minds. - `GET /api/v1/minds/{mindId}/knowledge` - List knowledge items - `POST /api/v1/minds/{mindId}/knowledge` - Add knowledge (links, files, or keyword search) - `PUT /api/v1/minds/{mindId}/knowledge/{itemId}` - Update a knowledge item - `DELETE /api/v1/minds/{mindId}/knowledge/{itemId}` - Delete a knowledge item - `POST /api/v1/minds/{mindId}/knowledge/enrich` - Enrich via keyword search (convenience alias) - `GET /api/v1/minds/{mindId}/knowledge/patterns` - Get knowledge patterns by framework ### Chat Interact with your minds via chat completions. - `POST /api/v1/chats` - Create a stateful single-Mind, multi-Mind, or Study chat - `POST /api/v1/chats/{chatId}/messages` - Continue a stateful chat - `DELETE /api/v1/chats/{chatId}` - Delete a stateful chat - `POST /api/v1/minds/{mindId}/completion` - Send messages and get responses ### Studies Create Studies, attach Audiences, and run cohesive multi-question research blocks. - `GET /api/v1/studies` - List all Studies - `POST /api/v1/studies` - Create a Study - `GET /api/v1/studies/{studyId}` - Get Study details with message history - `DELETE /api/v1/studies/{studyId}` - Delete a Study - `POST /api/v1/studies/{studyId}/ask` - Ask one genuinely standalone question - `GET /api/v1/studies/{studyId}/analytics` - Compute Study analytics - `POST /api/v1/studies/{studyId}/research-plans/preview` - Create or revise a cohesive question plan - `POST /api/v1/studies/{studyId}/research-runs` - Confirm and start an exact multi-question plan revision - `GET /api/v1/studies/{studyId}/research-runs/{runId}` - Poll durable research-run status - `POST /api/v1/studies/{studyId}/runs` - Start a durable direct run - `GET /api/v1/studies/{studyId}/runs` - List durable runs - `GET|POST /api/v1/studies/{studyId}/summary` - Read or refresh the semantic summary - `POST /api/v1/studies/{studyId}/export` - Export Study results as a report - `GET /api/v1/studies/{studyId}/export-status` - Check export job status - `GET /api/v1/studies/{studyId}/export-download` - Download the completed export ### User User-related endpoints. - `GET /api/v1/auth/me` - Get current authenticated user - `GET /api/v1/user/shareable-sparks` - List minds available for sharing ### API Keys Manage your API keys for authentication. - `GET /api/v1/api-keys` - List your API keys - `POST /api/v1/api-keys` - Create a new API key - `DELETE /api/v1/api-keys/{keyId}` - Delete an API key ## Quick Example Here's a quick example of creating a mind and chatting with it: ```bash # 1. Create a mind (keywords mode) curl -X POST "https://getminds.ai/api/v1/minds" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Marketing Expert", "description": "Expert in digital marketing strategies", "mode": "keywords", "type": "expert", "discipline": "Marketing", "keywords": ["SEO", "content marketing", "social media", "analytics"] }' # Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } } # 2. Create a mind from social profile (clone mode) curl -X POST "https://getminds.ai/api/v1/minds" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Influencer Clone", "description": "AI trained on influencer social presence", "mode": "clone", "type": "creative", "discipline": "Social Media Marketing", "personaContext": "https://twitter.com/username" }' # 3. Chat with the mind curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What are the top social media trends for 2025?" } ] }' ``` ## Next Steps - Learn about [Authentication](https://getminds.ai/docs/api/authentication) - Browse the [complete v1 endpoint catalog](https://getminds.ai/docs/api/reference) - Read the [API integration guide for agents](https://getminds.ai/docs/api/agents) - Explore [Minds endpoints](https://getminds.ai/docs/api/minds) - Read about [Knowledge management](https://getminds.ai/docs/api/knowledge) - Understand [Chat completions](https://getminds.ai/docs/api/chat) - Create [Studies](https://getminds.ai/docs/api/studies) for multi-Mind surveys - Review [Latency & Performance](https://getminds.ai/docs/api/latency) - Connect via [MCP Integration](https://getminds.ai/mcp/overview) - Review [Errors & Limits](https://getminds.ai/docs/api/errors) ## Plan Limits API access is available on supported paid plans and remains subject to the authentication, usage allowances, and workspace configuration shown in the product or agreed in your contract. Limits may differ by plan and can change; handle structured `plan_limited` and `429` responses instead of hard-coding allowances. Chats created through `POST /api/v1/chats` and Study sessions draw on the applicable chat or response allowance. The Individual plan is represented as `"premium"` in API payloads. The public defaults below are generated from the same plan-limit and feature-access contract used by the product. Account-specific and Enterprise contract overrides shown in the product take precedence. :plan-limits-table [View Plans](https://getminds.ai/settings?tab=subscription) ## Need Help? If you have questions or need support with the API: - Check our [Guide](https://getminds.ai/guide) - Contact us through the feedback form - Join our community discussions ## n8n workflows If you build automations in n8n, start with the [Minds community-node guide](https://getminds.ai/guide/integration-n8n). It packages five Study API operations for self-hosted workflows: create, list, inspect, preview a plan, and read a saved summary. Additional endpoints remain available through an HTTP Request node. # Minds v1 API Endpoint Catalog This catalog lists the complete customer-facing v1 route surface. Use it with the live [OpenAPI 3.1 document](https://getminds.ai/docs/api/openapi) for schemas and the [agent integration guide](https://getminds.ai/docs/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](https://getminds.ai/docs/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 | Method | Path | Purpose | MCP equivalent | | -------- | -------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- | | `GET` | `/api/v1/openapi.json` | Return the public OpenAPI 3.1 document; authentication is not required | MCP publishes protocol-native `tools/list` discovery | | `GET` | `/api/v1/auth/me` | Read the authenticated account identity and plan context | Intentionally transport context, not an MCP research tool | | `GET` | `/api/v1/api-keys` | List API-key metadata; secret values are never returned again | Intentionally excluded from MCP | | `POST` | `/api/v1/api-keys` | Mint an API key and return its secret once | Intentionally excluded from MCP | | `DELETE` | `/api/v1/api-keys/{keyId}` | Revoke an API key | Intentionally excluded from MCP | 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`. | Method | Path | Purpose | MCP equivalent | | -------- | ---------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `GET` | `/api/v1/minds` | List owned Minds with pagination and filters | `list_minds` | | `POST` | `/api/v1/minds` | Create and queue training for a Mind | `create_mind` | | `DELETE` | `/api/v1/minds` | Batch-delete confirmed Minds through canonical cleanup | `manage_mind` with `action: "delete_many"` (1–100 IDs per tool call) | | `GET` | `/api/v1/minds/library` | Read the first-party owned/shared library projection | `list_minds` | | `GET` | `/api/v1/minds/{mindId}` | Read one visible Mind | `manage_mind` with `action: "get"` | | `PUT` | `/api/v1/minds/{mindId}` | Update editable Mind fields and sharing configuration | `manage_mind` with `action: "update"` | | `DELETE` | `/api/v1/minds/{mindId}` | Delete one confirmed Mind and associated resources | `manage_mind` with `action: "delete"` | | `GET` | `/api/v1/minds/{mindId}/training` | Read training status and progress | `get_mind_status` or `manage_mind` with `action: "get_training"` | | `POST` | `/api/v1/minds/{mindId}/retrain` | Queue retraining and rebuild the complete stored knowledge index before ready | `manage_mind` with `action: "retrain"` | | `POST` | `/api/v1/minds/{mindId}/regenerate-image` | Regenerate the Mind profile image | `manage_mind` with `action: "regenerate_image"` | | `POST` | `/api/v1/minds/{mindId}/regenerate-prompt` | Regenerate the system prompt from current knowledge | `manage_mind` with `action: "regenerate_prompt"` | | `POST` | `/api/v1/minds/{mindId}/regenerate-embeddings` | Queue a fresh vector rebuild for every stored knowledge item | `manage_mind` with `action: "regenerate_embeddings"` | | `GET` | `/api/v1/minds/{mindId}/patterns` | Read raw Mind patterns when access permits | `manage_mind` with `action: "get_patterns"` | | `POST` | `/api/v1/minds/{mindId}/completion` | Run a stateless completion with one Mind | `chat_with_mind` | | `POST` | `/api/v1/minds/{mindId}/export` | Start or return a Mind profile export | `export_mind` | | `GET` | `/api/v1/minds/{mindId}/export-status` | Poll an asynchronous Mind export | `export_mind` returns status information | | `GET` | `/api/v1/minds/{mindId}/export-download` | Download a completed Mind export | `export_mind` returns the artifact or link | | `GET` | `/api/v1/user/shareable-sparks` | List Minds eligible for a sharing picker | `list_minds` | 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 | Method | Path | Purpose | MCP equivalent | | -------- | -------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- | | `GET` | `/api/v1/minds/{mindId}/knowledge` | List knowledge items | `manage_mind_knowledge` with `action: "list"` | | `POST` | `/api/v1/minds/{mindId}/knowledge` | Add a link, keyword search, multipart file, or URL-referenced file | `manage_mind_knowledge` with `action: "add"` | | `PUT` | `/api/v1/minds/{mindId}/knowledge/{itemId}` | Update description, watch state, or supported metadata | `manage_mind_knowledge` with `action: "update"` | | `DELETE` | `/api/v1/minds/{mindId}/knowledge/{itemId}` | Delete a knowledge item and associated stored artifact | `manage_mind_knowledge` with `action: "delete"` | | `GET` | `/api/v1/minds/{mindId}/knowledge/{itemId}/status` | Poll knowledge processing | `manage_mind_knowledge` with `action: "status"` | | `POST` | `/api/v1/minds/{mindId}/knowledge/enrich` | Convenience keyword-enrichment operation | `manage_mind_knowledge` with `action: "enrich"` | | `GET` | `/api/v1/minds/{mindId}/knowledge/patterns` | Read knowledge patterns by framework | `manage_mind_knowledge` with `action: "patterns"` | 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 | Method | Path | Purpose | MCP equivalent | | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | | `GET` | `/api/v1/audiences/limits` | Read private account/team Audience size ceilings; unavailable entitlements return `503` | `get_audience_limits` | | `GET` | `/api/v1/audiences` | List visible Audiences | `list_audiences` | | `POST` | `/api/v1/audiences` | Create an Audience from explicit Mind IDs | `create_audience` | | `GET` | `/api/v1/audiences/library` | Read the first-party owned/followed/shared library projection | `list_audiences` | | `GET` | `/api/v1/audiences/{id}` | Read members, access, grounding, and Formations | `get_audience` or `manage_audience` with `action: "get"` | | `PUT` | `/api/v1/audiences/{id}` | Update supported Audience fields and sharing configuration | `manage_audience` with `action: "update"` | | `DELETE` | `/api/v1/audiences/{id}` | Delete a confirmed Audience | `manage_audience` with `action: "delete"` | | `POST` | `/api/v1/audiences/{id}/members` | Add one or more Minds to an Audience | `manage_audience` with `action: "add_member"` | | `DELETE` | `/api/v1/audiences/{id}/members/{mindId}` | Remove one Mind from an Audience | `manage_audience` with `action: "remove_member"` | | `POST` | `/api/v1/audiences/{id}/follow` | Follow/save a visible public Audience | `manage_audience` with `action: "follow"` | | `DELETE` | `/api/v1/audiences/{id}/follow` | Unfollow a saved Audience | `manage_audience` with `action: "unfollow"` | | `GET` | `/api/v1/audiences/{id}/progress` | Read settled creation progress | `manage_audience` with `action: "get_progress"` | | `GET` | `/api/v1/audiences/active-progress` | Read active Audience/Mind build progress for the UI | Use per-Audience or per-Mind MCP status tools | | `GET` | `/api/v1/audiences/lifecycle/stream` | Stream user-scoped invalidation hints; clients re-read durable state after each event | MCP uses durable status reads instead of a browser SSE subscription | | `POST` | `/api/v1/audiences/{id}/recalibrate` | Replace stored grounding with refreshed authoritative research | `recalibrate_audience` | | `POST` | `/api/v1/audiences/{id}/regenerate-images` | Regenerate Audience member images with optional limits/dry run | `manage_audience` with `action: "regenerate_images"` | | `POST` | `/api/v1/audiences/source-import` | Import account-owned research files without creating an Audience; up to 20 files, 5 MiB each and 12 MiB supplied content, with a 24 MiB JSON body ceiling. Private responses; malformed input returns `400`, oversized requests `413`, storage failures `502`. Identical uploads can be retried. | `import_audience_sources` | | `POST` | `/api/v1/audiences/from-brief` | Create a grounded synthetic audience from a brief and sources | `create_audience_from_brief` | | `GET` | `/api/v1/audiences/from-brief/jobs/{jobId}` | Poll an asynchronous from-brief Audience creation operation | Polled automatically by `create_audience_from_brief` | | `POST` | `/api/v1/audiences/from-brief/segmentation-preview` | Review respondent variables with a 256 KiB JSON request limit; private responses, safe failures and role-based defaults | `preview_audience_dataset_segmentation` | | `POST` | `/api/v1/audiences/allocation-preview` | Non-mutating deterministic cohort-allocation preview | `create_audience_from_brief` cohort-allocation workflow | | `POST` | `/api/v1/audiences/{id}/export` | Start or return a branded Audience brief export | `export_audience` | | `GET` | `/api/v1/audiences/{id}/export-status` | Poll an asynchronous Audience export | `export_audience` | | `GET` | `/api/v1/audiences/{id}/export-download` | Download a completed Audience export | `export_audience` returns the artifact | 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 member additions require a JSON object within 64 KiB, including ignored fields. A `mindIds` array accepts at most 1,000 entries before deduplication; split larger additions into separate requests. Invalid JSON or excess IDs returns `400`; excess body bytes returns `413`. Legacy Group URLs enforce the same limits. Audience member additions use `mindId` or `mindIds` (`mindId` takes precedence). UUID case variants count as one ID; `data.added` includes IDs that were already members. The owner-only write rechecks ownership, Mind access, and remaining capacity in one transaction. Concurrent additions cannot both consume the last slot; a rejected batch adds nothing. Responses are private and non-cacheable, with generic `500` errors for unexpected storage or plan-resolution failures. Member removal is owner-only and atomically deletes the Audience membership plus that Mind’s subgroup assignments on the same Audience. It preserves the Mind itself and other Audiences. Ownership is rechecked within the write; transaction failure preserves both membership and assignments. Success is an empty `204`, even when membership was already absent. Missing/unowned Audiences return `404`, unexpected storage failures a generic `500`; responses are private and non-cacheable. ## Audience validation Audience Validation checks an Audience against real, published surveys and scores how close its Minds' answers are to the published answers. See [Validate an Audience against real surveys](https://getminds.ai/docs/api/audiences) for request options, results, costs, and failure codes. | Method | Path | Purpose | MCP equivalent | | ------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `POST` | `/api/v1/audiences/{id}/validations` | Start a validation against found surveys, 1–5 listed surveys, uploaded survey files, a dataset, or an existing Study run; optional `requestKey` or `Idempotency-Key`; returns `202` | `validate_audience` | | `GET` | `/api/v1/audiences/{id}/validations` | List validations newest first with overall validity, included validations, responses, and ready Minds | `get_audience_validation` without `batchId` | | `GET` | `/api/v1/audiences/{id}/validations/batches/{batchId}` | Read one validation: status, progress, survey scores and ranges, combined score, question selection, and failure | `get_audience_validation` with `batchId` | | `GET` | `/api/v1/audiences/{id}/validations/{validationId}` | Read one survey's scoring with every KPI and question | Summarized per survey by `get_audience_validation` | | `POST` | `/api/v1/audiences/{id}/validations/batches/{batchId}/cancel` | Stop a validation while `canCancel` is true | `validate_audience` with `action: "cancel"` | | `GET` | `/api/v1/audiences/validation-benchmarks?audienceId={id}` | Preview the surveys that would be used and how they fit | `validate_audience` finds fitting surveys itself | ## Audience Formations A Formation is a persisted segmentation of one Audience into defined subgroups. | Method | Path | Purpose | MCP equivalent | | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `GET` | `/api/v1/audiences/{id}/formations` | List visible shared/personal Formations with private, non-cacheable responses; unexpected lookup/seeding/storage failures return `500` | `list_formations` or `manage_formation` with `action: "list"` | | `POST` | `/api/v1/audiences/{id}/formations` | Create and compute a Formation | `manage_formation` with `action: "create"` | | `POST` | `/api/v1/audiences/{id}/formations/preview` | Generate a non-persisted segmentation hypothesis | `manage_formation` with `action: "preview"` | | `GET` | `/api/v1/audiences/{id}/formations/{formationId}` | Read one Formation | `manage_formation` with `action: "get"` | | `DELETE` | `/api/v1/audiences/{id}/formations/{formationId}` | Delete a confirmed Formation | `manage_formation` with `action: "delete"` | | `POST` | `/api/v1/audiences/{id}/formations/{formationId}/recompute` | Recompute member assignments | `manage_formation` with `action: "recompute"` | Formation listing is paginated: `limit` defaults to 100 (maximum 100), `offset` defaults to 0, and `pagination` returns `total`, `limit`, `offset`, `hasMore` and `nextOffset`. Select auto-dimension winners before counting or paging; timestamp ties use descending IDs. Follow `nextOffset` until `hasMore` is false. Each page is internally consistent, while concurrent changes can shift later offsets. Only offset 0 seeds defaults and checks stalled builds. Recovery checks at most 100 pending builds, oldest first; a failed attempt does not stop other selected attempts or prevent the list response. Reopen offset 0 to retry pending work. Both `list_formations` and `manage_formation` (`action: "list"`) expose the same page controls. Successful build completion checks for both missing and newly added Audience members. If the classified snapshot no longer matches, the worker requests a retry without replacing the saved buckets. A short database lock closes the gap between that check and committing the ready state. Empty or degenerate failure decisions also require an unchanged population; a cap failure requires the current member count to remain above the limit. Queued execution errors preserve `building` until the last configured attempt; exhaustion records a sanitized failure. The synchronous no-Redis path has one attempt and settles as failed on execution errors. Incremental classification commits a replacement assignment set for one Mind and one Formation; it does not accumulate the results of earlier classifications. Provider outages leave the saved set untouched. Numeric-balanced dimensions accept additional members only through explicit recomputation. Formation detail responses are private and non-cacheable. Only documented fields are exposed, and failure reasons are sanitized. Invalid legacy proposals become `{}`, malformed building progress becomes `null`, and ready builds always return `progress: null`. Invalid persisted detail metadata and unexpected storage errors return a generic `500`. Recompute can retain the previous completed subgroups until replacement succeeds, so check `status` before treating assignments as final. Formation creation accepts at most 64 KiB of JSON and returns private, non-cacheable responses. Its hypothesis must have non-empty text and 2–15 subgroups with unique trimmed IDs and labels; `unanswered`, `__unanswered`, and `__other` are reserved IDs. Invalid input returns `400`, oversized requests `413`, and unexpected storage errors a generic `500`. `name` is optional but must be a string. A user-created split requires two populated primary buckets to become `ready`. Deletion before acknowledgement returns `404`. Formation delete and recompute responses are private (`Cache-Control: private, no-store`), including refusals. Unexpected database or queue failures return a generic `500`; a missing or non-mutable Formation remains `404`. After an uncertain recompute response, inspect the Formation’s status before retrying. Preview request contract: body ≤64 KiB; optional `userInput` ≤2000 trimmed characters; optional `priorHypothesis` matching the creation schema (`null` also means no prior proposal). Empty requests use the default prompt. Input refusals are `400` or `413`; storage errors fail before streaming with a generic `500`. Responses prohibit caching. Generated output is validated and stripped to creation fields, including its serialized size. Generation errors use HTTP `500` for JSON and `error` → `done` events for an established NDJSON stream. Client disconnects and stream cancellation propagate an abort signal to the model executor. 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. Negotiation honors `q` weights, specific ranges, wildcards and UTF-8 media parameters; explicit rejection cannot be overridden by a less-specific wildcard. No header selects NDJSON. A request that accepts neither available representation receives a private `406` before the model is called. ## Studies, analytics, and exports | Method | Path | Purpose | MCP equivalent | | -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- | | `GET` | `/api/v1/studies` | List Studies | `list_studies` | | `POST` | `/api/v1/studies` | Create a Study from existing Audiences or inline `audienceConfigs` | `create_study` | | `GET` | `/api/v1/studies/{studyId}` | Read Study composition and history | `get_study_status` or `manage_study` with `action: "get"` | | `DELETE` | `/api/v1/studies/{studyId}` | Delete a confirmed Study | `manage_study` with `action: "delete"` | | `POST` | `/api/v1/studies/{studyId}/ask` | Submit one direct question; supports SSE and queued modes | `ask_study` | | `GET` | `/api/v1/studies/{studyId}/analytics` | Compute scale, categorical, and qualitative analytics | `get_study_analytics` | | `POST` | `/api/v1/studies/{studyId}/invitations` | Invite Study collaborators without exposing invitation tokens | `manage_study` with `action: "invite"` | | `POST` | `/api/v1/studies/{studyId}/export` | Start an export in a supported format | `export_study` | | `GET` | `/api/v1/studies/{studyId}/export-status` | Poll export status | `export_study` / `get_study_status` | | `GET` | `/api/v1/studies/{studyId}/export-download` | Download a completed export | `export_study` returns an artifact or link | | `POST` | `/api/v1/studies/{studyId}/heatmaps/{messageId}/export` | Start or return a website-heatmap ZIP export | `export_heatmap` | | `GET` | `/api/v1/studies/{studyId}/heatmaps/{messageId}/export-status` | Poll a website-heatmap ZIP export | `export_heatmap` | | `GET` | `/api/v1/studies/{studyId}/heatmaps/{messageId}/export-download` | Download a completed website-heatmap ZIP | `export_heatmap` returns a signed URL | | `GET` | `/api/v1/studies/{studyId}/summary` | Read the persisted flexible semantic summary | `get_study_summary` | | `POST` | `/api/v1/studies/{studyId}/summary` | Generate or refresh the semantic summary | `get_study_summary` with `refresh: true` | | `PUT` | `/api/v1/studies/{studyId}/sharing` | Enable or disable the public Study link | `manage_study` with `action: "set_link_sharing"` | 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. | Method | Path | Purpose | MCP equivalent | | ------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `POST` | `/api/v1/studies/{studyId}/research-plans/preview` | Create or revise a versioned research-plan draft | `plan_study_questions` | | `POST` | `/api/v1/studies/{studyId}/research-runs` | Confirm and run the exact reviewed plan revision | `run_study_questions` | | `GET` | `/api/v1/studies/{studyId}/research-runs/{runId}` | Poll Study progress, methods, artifacts, and calculations | `get_study_run` | | `POST` | `/api/v1/studies/{studyId}/runs` | Start a durable direct Study run | `ask_study` for direct questions or `run_study_questions` for planned research | | `GET` | `/api/v1/studies/{studyId}/runs` | List durable runs for a Study | `get_study_status` / `get_study_run` | | `GET` | `/api/v1/runs/{runId}` | Read durable run status | `get_study_status` / `get_study_run` | | `GET` | `/api/v1/runs/{runId}/events` | Read ordered run events using `after` and `limit` cursors | MCP status tools return durable progress | | `POST` | `/api/v1/runs/{runId}/cancel` | Cancel a running durable job | No dedicated curated MCP tool | | `GET` | `/api/v1/model-connections` | Page active team model connections and verified capability flags when enabled; pass `pagination.nextCursor` as `cursor` | `list_model_connections` | | `GET` | `/api/v1/research-methods` | List versioned methods, execution support, requirements, and fallbacks | `list_research_methods` | 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. ### Study templates Template responses are private and non-cacheable. Save and update accept JSON bodies up to 1 MiB; use accepts up to 4 KiB. Oversized requests return `413`, while malformed JSON or invalid configuration returns `400`. The configuration itself is limited to 512 KiB. Expected ownership, revision and file refusals retain their documented statuses; unexpected storage/provider failures return a generic `500`. | Method | Path | Purpose | MCP equivalent | | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `GET` | `/api/v1/study-templates` | List personal and team-shared templates | `list_study_templates` | | `GET` | `/api/v1/study-templates/{id}` | Read a visible template and its revision | `list_study_templates` | | `POST` | `/api/v1/study-templates` | Save a template; preserve `requestId` for retries | `manage_study_template` (`save`) | | `PATCH` | `/api/v1/study-templates/{id}` | Update an owned template using `expectedRevision` | `manage_study_template` (`update`) | | `DELETE` | `/api/v1/study-templates/{id}` | Delete an owned template | `manage_study_template` (`delete`) | | `POST` | `/api/v1/study-templates/{id}/use` | Create an independent app-editable draft using `expectedRevision` and `requestId`; retries return the existing draft | `manage_study_template` (`use`) | ## Durable Study drafts These endpoints persist the same resumable planner state used by the first-party Study sidebar. | Method | Path | Purpose | MCP equivalent | | -------- | ----------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------- | | `GET` | `/api/v1/study-drafts` | List owned resumable drafts | `list_study_drafts` | | `POST` | `/api/v1/study-drafts` | Create a durable draft | `save_study_draft` | | `GET` | `/api/v1/study-drafts/{id}` | Read one complete draft | `list_study_drafts` with `draftId` | | `PATCH` | `/api/v1/study-drafts/{id}` | Revise a draft using optimistic concurrency | `save_study_draft` with `draftId` and `expectedRevision` | | `DELETE` | `/api/v1/study-drafts/{id}` | Delete a confirmed draft | `manage_study_draft` with `action: "delete"` | | `POST` | `/api/v1/study-drafts/{id}/consume` | Mark a precise revision consumed and optionally attach it to a Study | `manage_study_draft` with `action: "consume"` | Draft responses use `Cache-Control: private, no-store`. Creation and update accept JSON requests up to 1 MiB, with a separate 512 KiB limit on the versioned `payload`; consume requests are limited to 4 KiB. Malformed JSON or invalid fields return `400`, oversized input returns `413`, and unexpected storage failures return a generic `500`. Saving an identical snapshot preserves its `revision` and `updatedAt`; a changed snapshot increments the revision and returns the snapshot written by that update, even if another writer immediately saves a newer revision. `POST /api/v1/study-drafts` accepts `idempotencyKey`: an optional string whose trimmed length is 1–200 characters. A matching key resolves to that caller’s previously saved draft, so a retry does not apply a replacement payload. Clients that omit this field have no key-based protection against duplicate creation. To edit an existing draft, send `PATCH /api/v1/study-drafts/{id}` with its latest `expectedRevision` in the JSON body; identify the draft in the URL rather than sending the MCP-only `draftId` argument. Always send the exact `expectedRevision` returned by the last read. A stale revision is rejected rather than overwriting newer active planning state. Consuming an already consumed draft returns its existing tombstone unchanged, including its linked Study. Consume closes planning state; it does not start or verify research. ## Stateful chats | Method | Path | Purpose | MCP equivalent | | -------- | --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------- | | `POST` | `/api/v1/chats` | Create a stateful single-Mind, multi-Mind, or Audience-backed chat | `manage_chat` with `action: "create"` | | `POST` | `/api/v1/chats/{chatId}/messages` | Append a user/system message and receive the next response | `manage_chat` with `action: "send_message"` | | `DELETE` | `/api/v1/chats/{chatId}` | Delete a confirmed chat and its persisted history | `manage_chat` with `action: "delete"` | 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](https://getminds.ai/docs/api/minds), [Audiences](https://getminds.ai/docs/api/audiences), [Studies](https://getminds.ai/docs/api/studies), [Knowledge](https://getminds.ai/docs/api/knowledge), and [Chat](https://getminds.ai/docs/api/chat) - Authentication and key rotation: [Authentication](https://getminds.ai/docs/api/authentication) - Errors, plan limits, and retry policy: [Errors & Limits](https://getminds.ai/docs/api/errors) - Autonomous integrations: [API guide for agents](https://getminds.ai/docs/api/agents) - Tool-native integrations: [MCP tools reference](https://getminds.ai/mcp/tools) # Minds API Integration Guide for AI Agents This guide is the operating contract for an AI agent that calls the Minds v1 REST API. It complements the [OpenAPI document](https://getminds.ai/docs/api/openapi), [complete endpoint catalog](https://getminds.ai/docs/api/reference), and domain walkthroughs. ## Choose REST or MCP | Need | Prefer | Why | | ---------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- | | Generate a typed SDK, run a backend integration, or control HTTP details | v1 REST API | Stable resource URLs, response envelopes, streaming, and durable job endpoints | | Let ChatGPT, Claude, Cursor, or another compatible assistant select research tools | MCP | Protocol-native tool schemas, annotations, OAuth, widgets, and presentation contracts | | Build a long-running service that resumes after process restarts | v1 REST API | Persist run, Study, draft, and export IDs in your own job state | | Run research interactively from a user conversation | MCP | Tool descriptions encode routing, confirmation, and safe presentation behavior | Both surfaces call the same v1 application boundaries for supported research actions. Do not combine REST and MCP in the same logical operation unless you have an explicit reason and a stable resource ID. ## Discovery checklist Read these resources before generating code or planning calls: 1. `https://getminds.ai/_openapi.json` — live OpenAPI 3.1 document for routes with detailed operation metadata. 2. `https://getminds.ai/api/reference` — complete v1 route catalog, including routes whose detailed OpenAPI schemas are still being expanded. 3. `https://getminds.ai/api/errors` — error envelope, plan limits, and retry behavior. 4. `https://getminds.ai/llms.txt` and `https://getminds.ai/llms-full.txt` — agent-oriented documentation discovery and consolidated reference text. 5. `https://getminds.ai/mcp/agents` — use this instead when your host supports MCP tools. Do not infer that a route is unavailable merely because it is not yet present in the generated OpenAPI document. The endpoint catalog is the completeness authority; the OpenAPI document is the schema authority for operations it includes. ## Authentication and secret handling Send a personal Minds API key as a bearer token: ```http Authorization: Bearer minds_… ``` Agent rules: - Read the key from a secret manager or environment variable. Never place it in prompts, source code, URLs, logs, traces, or error messages. - Use separate keys for development and production. - Treat the value returned by `POST /api/v1/api-keys` as write-only: it is shown once. - Do not let an autonomous agent rotate or revoke the key it is currently using. - On `401`, stop and request credential repair. Do not repeatedly retry. - On `403`, do not disguise an access-policy failure as “not found.” Explain that the authenticated account lacks access. ## Stable request wrapper Centralize authentication, JSON handling, timeouts, and error parsing: ```ts const MINDS_BASE_URL = 'https://getminds.ai/api/v1' type MindsError = { statusCode?: number statusMessage?: string message?: string data?: unknown } async function mindsRequest( path: string, init: RequestInit = {}, ): Promise { const response = await fetch(`${MINDS_BASE_URL}${path}`, { ...init, headers: { Authorization: `Bearer ${process.env.MINDS_API_KEY}`, ...(init.body ? { 'Content-Type': 'application/json' } : {}), ...init.headers, }, signal: init.signal ?? AbortSignal.timeout(120_000), }) const contentType = response.headers.get('content-type') || '' const payload = contentType.includes('application/json') ? await response.json() : await response.text() if (!response.ok) { const error = payload as MindsError throw new Error( `Minds ${response.status}: ${error.message || error.statusMessage || response.statusText}`, ) } return payload as T } ``` Use the apex form (`https://getminds.ai/api/v1`) if your infrastructure does not follow same-origin `307` redirects for API-subdomain `GET` requests. ## Plan before mutating Classify each proposed call: | Class | Examples | Agent behavior | | -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- | | Read-only | List/read resources, status, analytics, methods | May call when needed to answer the request | | Reversible creation/update | Create a private draft, update a name | State the intended target; preserve returned IDs | | Costly execution | Ask an Audience, run a Study, retrain, regenerate | Ensure it matches the user's request and avoid duplicate calls | | Public exposure | Enable link sharing | Require explicit intent; explain what becomes public | | Destructive | Delete Minds, Audiences, Studies, chats, Formations, drafts | Obtain explicit confirmation of exact IDs immediately before the call | | Credential control | Mint/revoke API keys | Keep outside autonomous research flows | Never enable `isLinkSharingEnabled` merely to make a result convenient to access. Private is the default. ## Use IDs as durable state Names are suitable for user interaction, but IDs are the integration contract. Persist: - `sparkId` after Mind creation; - `audienceId` after Audience creation; - `studyId` after Study creation; - `draftPlanId` and `revision` during research planning; - `studyId` or `runId` during execution; - `jobId` for exports; - `itemId` for knowledge ingestion; - `draftId` and `expectedRevision` for sidebar Study drafts. Do not re-list by fuzzy name after a successful create response. Doing so can select the wrong resource when names are duplicated. ## Asynchronous operations Several operations return before work is complete. | Start operation | Persist | Poll/read | | ---------------------------------- | ------------ | ------------------------------------------------------- | | Create Mind | `sparkId` | `GET /minds/{mindId}/training` | | Create grounded Audience | `audienceId` | `GET /audiences/{id}/progress` | | Add file/link knowledge | `itemId` | `GET /minds/{mindId}/knowledge/{itemId}/status` | | Ask a Study in queued mode | `runId` | `GET /runs/{runId}` and `/events` | | Run confirmed multi-question block | `runId` | `GET /studies/{studyId}/research-runs/{runId}` | | Export | `jobId` | entity-specific `export-status`, then `export-download` | Recommended polling behavior: 1. Honor `Retry-After` when returned. 2. Otherwise start at 1–2 seconds and exponentially back off to 10–15 seconds. 3. Add jitter when many jobs run concurrently. 4. Persist the last event cursor for `/runs/{runId}/events`. 5. Stop on terminal success, failure, cancellation, or `plan_limited`. 6. Set a workflow-level deadline; a client timeout does not prove the server operation failed. ## Idempotency and retries - Retry `GET` requests after transient `429`, `502`, `503`, or `504` responses using bounded exponential backoff. - Retry a mutation only when the endpoint documents idempotency or you supplied a stable idempotency key. - `create_audience_from_brief` derives an idempotency key from its arguments. Retry with exactly the same arguments after a timeout to recover the original Audience. - `run_study_questions` supports an explicit stable idempotency key through MCP; REST callers should preserve the confirmed draft ID/revision and returned Study ID. - Optimistic-concurrency failures on Study drafts require a fresh read and human/agent reconciliation. Do not overwrite with a guessed revision. - Never retry destructive calls merely because the client did not receive the response. Read the resource first to determine whether deletion already succeeded. ## Direct questions versus guided Studies Use this routing table: | User request | Route | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | One direct question to an existing Study | `POST /studies/{studyId}/ask` | | Knowledge-only durable direct run | `POST /studies/{studyId}/runs` | | Multiple questions, a broad objective, an asset audit, structured evidence outputs, or an explicit method | Plan → confirm → Study lifecycle | | Export existing evidence | `POST /studies/{studyId}/export` | | Show existing evidence differently | Read status/summary/analytics; do not recruit a new run | The guided lifecycle is: ```text POST research-plans/preview -> present the exact draft and every confirmation question -> revise the same draft if the user changes or answers anything -> receive explicit confirmation of the exact revision -> POST studies with that draft ID and revision -> poll GET studies/{studyId} -> GET or POST summary ``` Planning is non-executing. Never claim that research has started after a preview call. ## Method availability Call `GET /api/v1/research-methods` before promising a named method. Treat fields as follows: - `preparesQuestionsAtExecution: true` — the method generates deterministic questions and response contracts from its configuration at execution; saved template questions are not the full executed instrument. - `executable: true` — the registered server adapter can run the method. - `executable: false` — the method may be represented or planned but is not an execution promise. - Advanced methods require explicit opt-in at execution time. - Preserve deterministic calculations returned by the Study endpoint; do not recompute them with an LLM. ## File and URL inputs - Upload interactive browser files with multipart form data. - For autonomous agents, prefer public, short-lived signed, or Minds workspace-upload URLs. - Do not embed large binary files as base64 JSON. - Give every file a meaningful `name` and MIME `type` when known. - URLs may be rejected by SSRF and redirect guards even when they are syntactically valid. - Knowledge retrieval is bounded to 50 MB and a server timeout; split larger sources before ingestion. - For respondent datasets, preview segmentation before creating a representative cohort. ## Error decisions | Signal | Meaning | Agent response | | ------------------------------------- | ----------------------------------- | ------------------------------------------------------------------- | | `400` / validation details | Request does not satisfy the schema | Correct the payload; do not retry unchanged | | `401` | Missing/invalid/expired credential | Stop and repair authentication | | `403` | Authenticated but not allowed | Explain access/ownership/plan boundary | | `404` | Resource is absent or not visible | Verify the persisted ID and account context | | `409` | Revision/idempotency/state conflict | Read current state and reconcile | | `415` | Unsupported request media type | Correct `Content-Type` or file form | | `429` | Rate or usage limit | Honor `Retry-After`; distinguish rate limiting from `plan_limited` | | `plan_limited` before execution | Nothing started | Explain the required plan/allowance change | | `status: plan_limited` during a Study | Partial artifacts were preserved | Report completed versus remaining questions; never call it complete | | `5xx` | Transient or server failure | Bounded retry for safe/idempotent calls, otherwise read state first | ## Result presentation - Preserve citations, source URLs, shared links, download links, and resource IDs exactly. - Clearly label synthetic responses and distinguish them from primary human research. - Report status as queued/running/partial/completed/failed based on returned fields, not elapsed time. - For categorical or multiselect results, preserve the server's aggregation semantics instead of forcing percentages to sum to 100 when multiple selections are allowed. - Do not invent missing Mind answers or fill incomplete Study artifacts. - Use the authenticated workspace link for the owner and a returned shared link only for external handoff. ## Minimal autonomous Study example ```ts const studies = await mindsRequest<{ data: Array<{ id: string; name: string }> }>( '/studies', ) const study = studies.data.find(item => item.name === 'Launch research') if (!study) throw new Error('Study not found') const started = await mindsRequest<{ data: { runId: string } }>( `/studies/${study.id}/runs`, { method: 'POST', body: JSON.stringify({ question: 'What are the strongest objections to this positioning?', sourcePolicy: 'knowledge_only', }), }, ) // Persist started.data.runId before polling. ``` ## Preflight checklist Before a mutation, verify: - the authenticated workspace and plan context; - exact resource IDs and ownership/access; - whether the request is direct research or requires a confirmed plan; - whether sharing remains private; - whether a previous timed-out call may already have succeeded; - whether the operation consumes an allowance or triggers generation; - whether explicit confirmation is required. After a mutation, persist returned IDs, poll the documented status endpoint, and present only terminal or explicitly partial results. ## n8n workflows For an n8n AI Agent, attach the [Minds node as a tool](https://getminds.ai/guide/integration-n8n) and select a bounded Study operation. Store authentication in a Minds API credential, keep link sharing disabled unless publication is intended, and require separate review in Minds before research starts. # Minds MCP Server for ChatGPT, Claude, and Cursor Tool availability depends on deployment configuration: ordinary discovery exposes 23 tools, or 24 when `list_model_connections` is enabled, with 42 or 43 canonical tools registered respectively. Treat the connected server’s `tools/list` response as authoritative. Minds provides a Model Context Protocol (MCP) server that lets AI assistants create reusable Audiences, run cohesive multi-question Studies, and interact with individual Minds. This enables seamless integration with tools like ChatGPT, Claude Desktop, Cursor, and other MCP-compatible clients. ## What is MCP? The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external tools and data sources. With our MCP integration, you can: - Create and manage AI Minds (experts, personas, digital twins) - Build Studies with reusable Audiences of domain experts or consumers - Run survey-style questions across multiple perspectives - Get statistical analytics on Study responses - Export branded PDF reports, markdown summaries, or raw data - Organize Minds into reusable Audiences - Create grounded audiences from briefs or respondent datasets - Plan, explicitly confirm, run, and resume durable research Studies - Manage knowledge, Formations, lifecycle actions, and stateful chats ## MCP Server URL ```text https://getminds.ai/mcp ``` For setup instructions by client, see the [Minds MCP setup guide](https://getminds.ai/mcp/setup). For all 42–43 canonical tools and the 23–24-tool advertised surface, see the [Minds MCP tools reference](https://getminds.ai/mcp/tools). Agent authors should also read the [MCP operating guide for agents](https://getminds.ai/mcp/agents). ## Authentication The MCP server supports two authentication methods: - **OAuth 2.1** (recommended) — Clients like ChatGPT and Claude Desktop handle this automatically. You'll be prompted to log in to your Minds account when connecting. - **API Key** — For programmatic access, generate a key at Settings → API Keys (starts with `minds_`). Pass as `Authorization: Bearer minds_your_key`. ## Compatible Clients | Client | Tools | Widget | Auth | Setup | | --------------------- | :--------------: | :--------------: | :--------------: | --------------------------------- | | **ChatGPT** | 23–24 advertised | Client-dependent | OAuth | Settings → Apps | | **Claude Desktop** | 23–24 advertised | Client-dependent | OAuth or API key | Customize → Connectors | | **Claude Code** | 23–24 advertised | No | API key | `claude mcp add --transport http` | | **Cursor** | 23–24 advertised | Client-dependent | OAuth | Settings → MCP | | **Langdock** | 23–24 advertised | No | OAuth | Integrations → Add MCP | | **VS Code (Copilot)** | 23–24 advertised | Client-dependent | OAuth | Settings → MCP Servers | | **Windsurf** | 23–24 advertised | No | API key | MCP settings | All clients receive clickable links to open results in the Minds webapp, regardless of widget support. ## Advertised versus canonical tools `tools/list` returns 23–24 curated tools designed for ordinary interactive research. The server also keeps 19 additional canonical lifecycle and compatibility tools registered, for 42–43 canonical tools in total. Explicit integrations can call those tools by canonical name when the client supports configured or direct tool calls. This split keeps the default model surface focused while preserving the full supported capability contract. Tool aliases may remain callable for compatibility, but agents should always use canonical names from the [tools reference](https://getminds.ai/mcp/tools). ## Interactive Preview Minds currently registers three MCP views: creation progress, Study results and conversations, and research-plan review. They reuse Minds UI components. The client determines the surrounding frame and available interactions. The information preview below is illustrative; lookup tools return structured/text results without opening that view. The current plan view displays the saved draft for review. Request changes in the conversation, then explicitly confirm the latest revision before the assistant runs it. Viewing a plan does not start a Study. When a widget detects a mobile host, it displays a link to continue in Minds; interactive controls and widget polling do not start. This changes the widget presentation, not the MCP server's tool availability. Client restrictions still apply. The examples below use illustrative data. Switch tabs to inspect creation, information, and response states; loading examples are fixed snapshots, not live research. :mcp-widget-preview ## n8n workflows Building an n8n automation instead of an MCP client? The [Minds n8n integration](https://getminds.ai/guide/integration-n8n) connects directly to the Study API and can serve as an AI Agent tool. The npm package supports self-hosted n8n while n8n verification remains under review. # Minds MCP Tools Reference Tool availability depends on deployment configuration: ordinary discovery exposes 23 tools, or 24 when `list_model_connections` is enabled, with 42 or 43 canonical tools registered respectively. Treat the connected server’s `tools/list` response as authoritative. The [Minds MCP server](https://getminds.ai/mcp/overview) advertises 23–24 curated tools through ordinary `tools/list` discovery and registers 42–43 canonical tools in total. The product model is deliberately small: an **Audience** is a reusable collection of Minds, while a **Study** is the research workspace that contains one or more Audiences, questions, evidence, results, and exports. Compatibility names containing `group` or `panel` remain callable, but new integrations must use the Audience and Study names documented here. The **Advertised** label below means ordinary clients discover the tool automatically. **Explicit** means the canonical tool is registered and callable by integrations that can configure or invoke a known tool name, but it is omitted from the curated discovery surface. Read the [agent operating guide](https://getminds.ai/mcp/agents) before autonomous use. MCP returns a public Study or Audience link only when the API reports `isPublic: true` or `isLinkSharingEnabled: true` and supplies a share ID. A retained share ID after revocation is not an active link. Use returned URLs exactly as provided. Name-based lookup searches at most the newest 1,000 visible Minds, Audiences or Studies. For an older record, browse the corresponding list tool with `limit` and `offset`, then pass its exact ID. Incomplete or malformed list responses return an error rather than claiming that no matching record exists. ## Curated advertised surface | Domain | Tools | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Minds | `export_mind` | | Audiences | `list_audiences`, `import_audience_sources`, `get_audience_limits`, `create_audience_from_brief`, `ask_audience`, `export_audience` | | Studies | `list_studies`, `list_model_connections`, `create_study`, `ask_study`, `get_study_status`, `export_study`, `export_heatmap`, `study_heatmap` | | Guided research | `plan_study_questions`, `run_study_questions`, `get_study_run`, `list_research_methods`, `list_study_drafts`, `save_study_draft`, `list_study_templates`, `manage_study_template`, `get_study_summary` | ## Minds & Audiences ### list\_minds Browse Minds owned by the authenticated user one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match among the newest 1,000 Minds. **Parameters:** - `searchQuery` (optional): Best fuzzy name match among the newest 1,000 Minds - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Entries to skip, default 0; use the previous result’s `nextOffset` **Example:** ```text "List my AI minds about marketing" ``` ### create\_mind Create a new Mind — a synthetic expert, consumer persona, or digital twin. **Parameters:** - `name` (required): Name of the Mind - `mode` (required): Training mode — `keywords`, `clone`, `link`, or `manual` - `type` (optional): Type — `creative`, `expert`, or `user` (default: `expert`) - `discipline` (optional): Area of expertise - `keywords` (optional): Topics for training (required for `keywords` mode) - `personaContext` (optional): Person to model (required for `clone` mode) - `contextLink` (optional): URL to train from (required for `link` mode) - `description` (optional): What this Mind specializes in - `includeWebSearch` (optional): Set `false` to skip automatic web research; use `manual` for a strictly source-only Mind - `idempotencyKey` (optional UUID): Choose one key before creating and reuse it with the same inputs for retries, including after timeouts. Use a fresh key for another Mind. The result returns the operation key in `structuredContent.idempotencyKey`. Without an explicit key, only identical calls within 10 seconds in the same server process are coalesced; cross-process or later retries need the returned key. | Mode | Description | Required Fields | | ---------- | --------------------------------- | ---------------- | | `keywords` | Train from topic keywords | `keywords` | | `clone` | Create a digital twin of a person | `personaContext` | | `link` | Train from website content | `contextLink` | | `manual` | Manual configuration | None | ### chat\_with\_mind Send one message to a Mind and get its response. Use `mindId` for an exact selection or `mindName` for the best fuzzy match among the newest 1,000 Minds. Browse `list_minds` by offset to find older Minds and pass their exact IDs. Use `manage_chat` for a persistent multi-turn conversation. **Parameters:** - `mindId` (optional): Mind UUID (use this OR `mindName`) - `mindName` (optional): Name with fuzzy matching (e.g., "my marketing expert") - `message` (required): Message to send - `sourcePolicy` (optional): `auto` or `knowledge_only` - `modelConnection` (optional): Verified caller-team connection ID and revision ### get\_mind\_status Check training progress after creating a Mind. **Parameters:** - `mindId` (required): Mind UUID ### export\_mind Export a Mind profile. This tool is **Advertised**. **Parameters:** - `mindId` or `mindName`: Exact UUID or the best fuzzy name match among the newest 1,000 Minds; use an exact UUID for older Minds - `format` (optional): `md`/`markdown` (default, returned inline), `pdf`, `docx`, or `pptx` The tool polls asynchronous generation internally. A successful result includes `filename`, `mimeType`, and either inline Markdown `content` or binary `contentBase64`, plus the Mind’s workspace link. Preserve these fields when saving the export. ### list\_audiences List visible Audiences one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries. **Parameters:** - `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 - `includeMinds` (optional): Include member Minds, default `false` ### create\_audience Create a reusable Audience from existing Minds. **Parameters:** - `name` (required): Audience name (e.g., "Marketing Experts") - `mindIds` (required): Mind IDs to add — use `list_minds` to find IDs ### import\_audience\_sources Results are private and non-cacheable. The tool verifies the returned file count/order, source policy, snapshot checksum and distribution references before reporting success. Keep the returned snapshot unchanged for preview or creation. Missing or foreign files are input errors; storage outages return `502` without provider details. Retry the same import after a storage failure or an invalid acknowledgement: content-addressed uploads preserve existing files. The MCP HTTP request body is limited to 24 MiB, including JSON escaping and protocol fields; oversized requests return HTTP `413` with a JSON-RPC error. Source-import file and total-content limits still apply separately. Import supplied UTF-8 `.txt`, `.md`, `.csv`, or `.json` sources using `files: [{ name, content }]`. Optional `existingFiles` and `groundingJson` preserve reviewed source context. This advertised tool creates no Audience and does not independently verify supplied distributions. ### get\_audience\_limits The tool validates account/team provenance, numeric ceilings and a complete, unique set of creation modes before reporting limits. A zero per-Audience cap is a workspace lock, not missing data. Responses are private and non-cacheable. Blocked credentials are revalidated; an unavailable entitlement lookup returns `503` without inventing a free-plan allowance. Read this account’s Audience size and creation-mode limits before choosing a size. Optional `mode` filters the result. Distinguish the automatic sizing ceiling from the explicit-count ceiling. This tool is advertised. ### create\_audience\_from\_brief Create a grounded synthetic audience from a population brief, source links, keywords, and research files. This tool is **Advertised** and private by default. Important parameters include: - `brief` (preferred) or legacy `text`: Population description - `name`: Audience name - `links`, `keywords`, `files`: Research context - `includeWebSearch`: Set `false` for file-only grounding - `memberCount`: Requested cohort size, subject to plan allowance - `audienceCreationMode`: `balanced`, `segment_coverage`, or `benchmark_depth` - `datasetSegmentation`: Reviewed output from `preview_audience_dataset_segmentation` - `cohortAllocation`: Deterministic marginal/joint allocation configuration - `isLinkSharingEnabled`: Enable only after an explicit request for a public link Identical arguments are idempotent for approximately six hours. After a timeout, retry the same arguments to recover the original Audience. Deeper creation modes are Team-plan workflows; inspect the effective mode returned by the server rather than assuming the request was accepted unchanged. While creation runs, every open workspace for the authenticated owner is notified through the user-scoped lifecycle stream and re-reads the same durable creation state. The UI therefore displays the same Drafting, Creating, and Ready states for UI, REST, and MCP creation. Repeating identical arguments reuses that lifecycle instead of duplicating the Audience. Use `groundingPreview: true` to review profiles and source findings before creation. Return `reviewedGroundingJson` and `reviewedGroundingSha256` unchanged with the same inputs and `memberCount` to create the accepted composition. If the tool returns a pending `structuredContent.operation`, call `create_audience_from_brief` again with only `operationId` set to its `jobId`. This resumes the existing operation without creating or charging for a second Audience. Completed results contain `structuredContent.preview` or `structuredContent.audience`. ### preview\_audience\_dataset\_segmentation Preview requests accept at most 256 KiB of JSON. Responses, including refusals, are private and non-cacheable. Invalid JSON or fields return `400`, an oversized request or dataset returns `413`, and Team eligibility or upload-access refusals return `403`. Entitlement lookup failures return `503`; unexpected download, classifier or analysis failures return a generic `500`. Omitting `segmentationColumns` selects the default population and segmentation variables, not every non-identifier field. MCP validates the complete aggregate response and reconciles row totals, selected variables and reported discovery counts before describing the analysis. Undeclared fields are omitted. Older responses without relationship or dependency counts are described as unreported, not zero. This is a review of the source dataset: it does not create a cohort or verify its eventual allocation. Authorized Minds uploads are read through their storage-access checks. Every network fallback, including a URL on the Minds host, uses the public-URL guard and validates redirect destinations; same-origin URLs do not bypass private-network protection. Downloads retain a 50 MiB streaming limit and a 30-second timeout. Failed HTTP responses are cancelled before an error is returned. Inspect a CSV, XLS, or XLSX respondent dataset before representative cohort creation. This is an **Explicit** Enterprise workflow. **Parameters:** - `file.name`: Original spreadsheet filename - `file.url`: Public, signed, or Minds workspace-upload URL - `segmentationColumns` (optional): Reviewed column keys from a previous preview The tool classifies file content, uses all completed respondent rows, identifies structural versus held-out variables, and recommends a representative Mind count. It never creates one Mind per respondent. Screeners and questionnaire programming grids are rejected as respondent data and should be passed directly to `create_audience_from_brief`. ### get\_audience Read an Audience's members, grounding, source metadata, sharing state, and Formations. This is an **Explicit** tool. **Parameters:** pass `audienceId` or `audienceName`. Name lookup is fuzzy, so do not call `list_audiences` first solely to resolve a natural user reference. ### ask\_audience Ask one existing Audience a direct research question. This tool is **Advertised**. It creates a private one-Audience Study, submits the question, and returns immediately; poll `get_study_status` for results. **Parameters:** - `audienceId` or `audienceName` - `question` (required) - `name` (optional): Internal Study name - `attachments` (optional): Reusable file/image context with a `url` or storage `path` Use `ask_study` when the user already has a multi-Audience Study. Each `ask_audience` call creates a new private wrapper Study. ### recalibrate\_audience Refresh and replace an Audience's stored grounding from authoritative web research, then re-allocate the members' cohort profiles to match the refreshed distributions — the same distributions-to-members logic the drafting flow uses. The instruction's reach decides how deeply members change, covering demographic, psychographic, behavioral, and firmographic amendments alike: composition or evidence edits ("make men 40%", "add an income distribution") touch only members whose allocation cell actually changed; trait changes ("now they're all vegan", "SMB owners instead of enterprise buyers") make members evolve in place — same Mind, same name and portrait, rewritten role and description, knowledge retrained; population pivots ("now African consumers") rebuild every member in place — same Mind, new persona and portrait, knowledge wiped and retrained — so studies, shares, and chat history keep working while the Minds genuinely become the new audience. No Minds are deleted; retraining runs asynchronously and the Audience shows build progress until it finishes. An additive instruction ("and now add 10 African consumers") grows the roster instead: new members are generated for the added audience within the plan's member limits. While the research runs the Audience reports a **Calibrating…** state in the app and via `get_audience`. This is an **Explicit** tool and owner-only. **Parameters:** `audienceId` or `audienceName`, plus optional `instruction` for a user adjustment on top of the original brief (for example "add an income distribution"), or `query` only when the user wants to steer research away from the original brief entirely. ### validate\_audience Check an Audience against real, published surveys: the tool finds surveys whose respondents best match the Audience, asks its Minds the same questions, and scores how close their answers are to the published answers. This is an **Explicit** tool: it is registered and callable by name for MCP clients that call tools directly, but it is not yet listed in assistants' tool discovery. The same capability is available now through the v1 API and the Audience's Validation tab. It writes, and it may search the web for fitting surveys. **Parameters:** - `audienceId` or `audienceName`: Exact UUID or fuzzy-matched Audience name - `action` (optional): `start` (default) or `cancel` - `benchmarkIds` (optional): 1–5 listed surveys to validate against; without them, the best-fitting published surveys are found - `batchId`: The validation to stop; required for `cancel` - `idempotencyKey` (optional UUID): Reuse the same key when retrying a start, so the retry returns the same validation instead of starting another The result gives the batch ID and status, says whether the run uses an included validation or synthetic responses, and tells the assistant to poll `get_audience_validation`. The Audience needs at least 10 ready Minds. A run usually takes 10 to 60 minutes and can be cancelled before any survey is asked. See [Audience validation in the API](https://getminds.ai/docs/api/audiences) for costs, limits, and failure codes. ### get\_audience\_validation Read an Audience's validations. This is an **Explicit**, read-only tool, callable by name but not yet listed in assistants' tool discovery; the same results are available through the v1 API and the Audience's Validation tab. **Parameters:** - `audienceId` or `audienceName` - `batchId` (optional): One validation to read With `batchId`, the result gives the status, progress, the combined score and its 95% range, each survey with its score, range, who it asked relative to the Audience, and its source, and which questions were left out and why. Without `batchId`, it gives the Audience's overall validity, its latest validation, the included validations left this month, and ready Minds against the minimum. A score of 100 means the Minds' answers match the published answer shares exactly. Report each survey's score with its range and who the survey asked, rather than the combined score alone. ### list\_formations On the first page (`offset: 0`), recovery checks at most 100 pending builds, oldest first. One failed attempt does not stop attempts for the other selected builds or prevent the list from being returned. Check build status and reopen the first page to retry pending work. `list_formations` and `manage_formation` with `action: "list"` accept optional `limit` and `offset`. Each call returns one page, with a default/maximum of 100. Follow `pagination.nextOffset` while `hasMore` is true. For `list_formations`, `totalCount` is the full visible total, not the number shown. An empty page beyond the end does not mean the Audience has no Formations. Malformed continuation metadata produces a tool error. The app and Study widget collect all summary pages before publishing a complete list; a failed continuation does not become a partial breakdown. You can list Formations on any Audience you can view, including shared Formations and your own private ones. MCP rejects malformed lists or missing membership counts instead of reporting an empty list or zero members. Counts are final only for `ready` Formations; `building` and `failed` counts are provisional. An empty first page with `total: 0` means no Formations are visible to you; opening it seeds defaults only for Audience editors. The v1 list response is private and non-cacheable, including refusals. Unexpected access-lookup, seeding or list-storage failures return a generic `500`. List persisted Formations for an Audience. This is an **Explicit** tool. Pass `audienceId` or `audienceName`. ### export\_audience Export an Audience brief through the canonical v1 API and unified branded renderer. This tool is **Advertised**. **Parameters:** - `audienceId` or `audienceName`: Exact UUID or fuzzy-matched Audience name - `format` (optional): `md`/`markdown` (default), `pdf`, `docx`, or `pptx` - `force` (optional): Regenerate instead of returning a cached artifact The tool polls the original export job and returns success only when a complete artifact is available. Preserve `filename`, `mimeType`, and Markdown `content` or binary `contentBase64`. Inline Markdown is capped at 100,000 characters and marked `_[truncated]_` when shortened. Cancellation stops polling; an unfinished export is an error, so check again without `force=true`. ## Studies (Multi-Mind Research) ### list\_model\_connections List active model connections for the authenticated team. A listed connection is not necessarily verified: inspect its capability flags and `verifiedAt` before selecting it. Pass `pagination.nextCursor` as the next request’s `cursor`. Only declared connection metadata and capability fields are returned; provider credentials, raw probes and undeclared diagnostics are omitted. Malformed responses or non-advancing cursors are errors. Unexpected discovery storage failures return a generic `500`. The tool is advertised only when model connections are enabled on the connected server. ### create\_study Create a Study workspace and attach one or more existing or inline Audiences. **Parameters:** - `name` (required): Study name - `audienceConfigs` (optional): New Audiences to create inline — each with `name` and `mindIds` - `audienceIds` (optional): Existing Audience IDs to attach **Example:** ```text "Create a Study called 'Brand Perception Study' with two Audiences: - 'Marketing Experts' containing my SEO and Content Marketing minds - 'Consumer Insights' containing my Gen Z and Millennial minds" ``` ### ask\_study Submit exactly one standalone research question to all selected Audiences in a Study. Treat the entire `question` value as respondent-visible input. The system may classify or reformat it, but any text in this field can reach the selected Minds and influence their answers. Put only the question, stimulus, and respondent-facing instructions here. For a questionnaire, survey, battery, section, cohesive question set, or any request with two or more known questions, use `plan_study_questions` once with the complete set—never call `ask_study` question by question. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `question` (required): Research question - `audienceIds` (optional): Only query specific Audiences ### list\_studies List Studies with their Audience composition and question counts, one page at a time. Preserve `nextOffset` to continue; `searchQuery` returns the best fuzzy match within the newest 1,000 entries. **Parameters:** - `searchQuery` (optional): Filter by name using fuzzy search - `limit` (optional): Page size, default 20, maximum 100 - `offset` (optional): Number of entries to skip, default 0 ### get\_study\_status `questionId` limits individual-answer reads and returned results to that question; the tool still reads the Study transcript metadata. Run status reads follow all relevant cursor pages. A failed or incomplete run-list read returns a tool error instead of successful partial status. Get detailed Study information including in-progress questions, completed results, and export status. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `questionId` (optional): Return one question's results - `exportKind`, `exportFormat`, `exportJobId` (optional): Use the exact kind, format and job ID returned by `export_study` to inspect that artifact Report queued, running, failed and partial work as such. A polling timeout does not authorize a new submission. ### get\_study\_analytics Compute statistical analytics across a Study's question history. **Returns:** - **Scale questions**: Mean, median, standard deviation, consensus, Audience rankings - **Categorical questions**: Distribution, dominant category, cross-Audience divergence - **Qualitative questions**: Theme clustering, shared themes, diversity index **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) ### export\_study Export Study results as a report. **Parameters:** - `studyId` (optional): Study UUID - `studyName` (optional): Study name (fuzzy matched) - `format` (optional): `pdf` (default), `docx`, `pptx`, `csv`, `xls`, `sav`, `md`, or `markdown` - `kind` (optional): `executive_brief`, `full_report` (default), or `raw_data` - `length` (optional): `brief`, `standard`, or `detailed` - `force` (optional): Regenerate instead of returning a cached artifact | Format | Description | | ----------------- | --------------------- | | `pdf` | Branded PDF report | | `docx` | Editable Word report | | `pptx` | Editable presentation | | `csv` | CSV workbook export | | `xls` | Excel workbook export | | `sav` | SPSS raw-data export | | `md` / `markdown` | Markdown report | ### study\_heatmap Read or start an asset heatmap with `studyId` or `studyName`, `messageId`, and `action: "get"` (default) or `"start"`. Optional `assetKey` selects an image/video assigned to that question. Starting analysis requires Premium and consumes one response per Mind; completed analysis is reused. This tool is advertised. ### export\_heatmap Export a completed website heatmap as the same ZIP archive available in the web app. The archive includes a unified-renderer PDF report, Markdown, source images, and metadata. This tool is **Advertised**. **Parameters:** - `studyId` or `studyName`: Study identifier - `messageId` (required): Completed Study message containing the website heatmap - `force` (optional): Regenerate instead of returning the cached archive ## Guided Research Planning ### plan\_study\_questions Create or revise one durable, versioned research-plan draft. Use it for every broader objective, questionnaire, survey, battery, section, cohesive question set, visual-asset analysis, structured research output, or named method. Put every question already known into one `request`; the planner may organize them into named modules or sections, but the agent must never create one plan or run per question. Do not use it for a standalone export or a request to show existing results differently; use `export_study` or `get_study_summary` for those requests. The free-form `request` is planner input and is not sent verbatim to Minds. The tool returns one cohesive plan with the exact proposed respondent-visible question text, named modules when useful, captured intent, main source, methods, semantic outputs, and explicit `confirmationQuestions`. The assistant must present the complete draft and those questions—including any framing warning—and must not claim the research has started. If the user changes anything, call the tool again with `draftPlanId` and `revision`. ### run\_study\_questions Confirm and run the exact latest draft revision only after explicit user confirmation. Advanced methods require `advancedMethodOptIn: true`. The catalog includes executable Conjoint, MaxDiff, NPS, top/bottom box, key drivers, TURF, Gabor-Granger, Van Westendorp, Kano, ranked preferences, and segment comparison. Check `list_research_methods` for `executable: true` and the required configuration before promising a method. If the Study-answer allowance is already exhausted, the tool returns a structured `plan_limited` error and the study does not start. Tell the user plainly that an upgrade is required; do not describe the survey as queued or completed. ### get\_study\_run Read durable status, question progress, the immutable confirmed plan, the separate server-prepared execution plan, the exact respondent-visible question audit, method stages, response artifacts, and deterministic method calculations for a study started by `run_study_questions`. `plan_limited` means an in-progress survey stopped before all questions completed. Preserve its partial artifacts, state how many questions completed, and tell the user to upgrade before starting a follow-up run for the remainder. ### list\_research\_methods `preparesQuestionsAtExecution: true` means the method derives deterministic questions and response contracts from its configuration at execution; saved template questions are not the complete executed instrument. Invalid catalog responses are errors, not an empty catalog. `includePlanned: false` excludes planned methods but still shows experimental methods with their non-executable status. List versioned methods with `executable`, availability, complexity, configuration requirements, semantic outputs, and fallbacks. Use this when the user explicitly asks for MaxDiff, NPS, Kano, TURF, pricing methods, Conjoint, or methodological options. A represented method is not necessarily runnable; only `executable: true` is an execution promise. Keep the default workflow simple when users do not ask for methodological complexity. The catalog entries `visual-asset-analysis` and `recommendation-synthesis` remain experimental and cannot execute as those named planner methods. Their `fallbackMethodId` identifies an alternative to review, not permission to silently substitute it. Image/video/website research and asset heatmaps have separate supported paths; use `study_heatmap` for an asset already assigned to a Study question. A non-executable planner entry does not mean MCP cannot analyze visual assets. ### list\_study\_drafts List active Study drafts or retrieve the complete saved planning state by `draftId`. A `draft` can be resumed from its saved step and revision; `starting` means launch is already in progress. An exact-ID read can return a `consumed` tombstone, which cannot be resumed. Invalid or incomplete API responses are errors, not an empty list or proof of a successful save. ### save\_study\_draft For creation, choose an optional `idempotencyKey` (1–200 characters after trimming) before the first request and reuse it after an uncertain result. Reusing the key returns the existing saved draft rather than applying new planning inputs. Omit it when updating: use `draftId` and the current `expectedRevision` instead. Without a key, repeated creation requests can create separate drafts. Create or revise a durable Study planning draft without starting research. A revision requires the exact `draftId` and `expectedRevision`; the tool saves a closed set of planning inputs into the same versioned Custom planner state used by the Minds sidebar. The backing v1 endpoints return private, non-cacheable responses. Create/update JSON requests are limited to 1 MiB, with a separate 512 KiB cap on the versioned `payload`; consume requests are limited to 4 KiB. Invalid input returns `400`, oversized input `413`, and unexpected storage failures a generic `500`. An unchanged snapshot preserves `revision` and `updatedAt`. Check saved state before retrying an uncertain save; a save itself does not start research. ### get\_study\_summary Retrieve the persisted semantic summary, or refresh it when `refresh: true`. Blocks are flexible evidence descriptors rather than fixed UI components. Preserve heatmap outputs for website, image, ad, and video analysis. ### list\_study\_templates The response must contain complete template identities, revisions, permissions and valid configurations. An exact `templateId` read must return that same template. Missing, malformed or mismatched responses are errors; only a valid empty list means no templates were returned. List owned and team-shared Study templates, or supply `templateId` to read one template including its current revision and stored configuration. This tool is **Advertised**. Reading a template does not launch research. ### manage\_study\_template The v1 template endpoints return private, non-cacheable responses. Save/update JSON bodies are limited to 1 MiB, and use bodies to 4 KiB (`413` above the limit); the saved configuration remains limited to 512 KiB. Malformed JSON or invalid input returns `400`. Expected ownership, revision and asset refusals retain their documented status; unexpected storage/provider failures return a generic `500`. The tool validates each write acknowledgement before reporting success: save/update must return the expected complete template, delete must return `success: true`, and use must return a Study draft. A retried use may return an existing `starting` or `consumed` draft; it is not described as a newly editable draft. If the acknowledgement is incomplete, inspect saved templates or drafts before retrying, and preserve the original request ID. Save, update, use or delete a Custom Study template. This tool is **Advertised**. Set `action` to `save`, `update`, `use` or `delete`; non-save actions require `templateId`. Provide the matching `save`, `update` or `use` object for that action. Only owners can update, delete or change team sharing. Use the current revision for updates and use. Preserve `save.requestId` for retry-safe creation; `use.requestId` must be a fresh UUID for each intended draft and reused only for a retry of that same request. `use` creates an independent editable draft to finish in the web app; it never starts research. Audiences and context are entered fresh. Review changes and confirm destructive actions before executing them. ## Explicit lifecycle tools These seven registered canonical tools expose the remaining v1 research lifecycle. They are intentionally omitted from the 23–24-tool curated discovery list until their product presentation is reviewed. An integration that calls one explicitly must supply the canonical schema and honor destructive/confirmation annotations. ### manage\_mind For `regenerate_image`, pass `force: true` to replace an existing portrait; otherwise a Mind that already has an image is skipped. Optional `personaContext` (1–16,000 characters after trimming) steers the portrait without changing the system prompt. Missing or invalid API acknowledgement envelopes produce an error with advice to inspect current state before retrying. A returned request does not establish completion of background training, images, knowledge ingestion or segmentation; inspect the returned status and counts. | Action | Required | Effect | | ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `get` | `mindId` | Read one Mind | | `update` | `mindId` | Update supported `name`, `description`, `discipline`, `systemPrompt`, `sourcePolicy`, `tags`, or sharing state | | `delete` | `mindId`, explicit confirmation | Delete one Mind through canonical cleanup | | `delete_many` | `mindIds` (1–100), explicit confirmation | Batch-delete confirmed Minds and report independent outcomes | | `retrain` | `mindId` | Queue retraining with a complete stored knowledge-index rebuild | | `regenerate_image` | `mindId` | Regenerate the profile image | | `regenerate_prompt` | `mindId` | Regenerate the system prompt | | `regenerate_embeddings` | `mindId` | Queue a full rebuild of the stored knowledge vectors | | `get_training` | `mindId` | Read training status | | `get_patterns` | `mindId` | Read raw patterns when permitted | ### manage\_mind\_knowledge For `action: "list"`, pass optional `limit` (1–100) and `offset` (0 or greater). The default page contains at most 100 items. Read `data.pagination.hasMore` and advance the offset to continue; `data.total` describes the entire collection. See [knowledge pagination](https://getminds.ai/docs/api/knowledge) for ordering and consistency limits. All actions require `mindId`. | Action | Additional inputs | Effect | | ---------- | -------------------------------------------------------------------------------- | ------------------------- | | `list` | `limit`, `offset` | List items | | `add` | One of `link`, `keywords`, or `file`; optional `description`, `regeneratePrompt` | Queue knowledge ingestion | | `update` | `itemId` and supported fields | Update an item | | `delete` | `itemId`, explicit confirmation | Delete an item | | `status` | `itemId` | Read processing status | | `enrich` | `keywords` | Run keyword enrichment | | `patterns` | — | Read knowledge patterns | `file` has `{ name, url, type? }`. The URL must be public, short-lived signed, or a Minds workspace-upload URL. Retrieval is SSRF-guarded, time-bounded, and limited to 50 MB; do not embed base64 binary data. ### manage\_audience All actions require `audienceId`. | Action | Additional inputs | Effect | | ------------------------------ | ------------------------------------------------ | ------------------------------------------------- | | `get` | — | Read Audience details and grounding | | `get_progress` | — | Read settled build progress | | `follow` / `unfollow` | — | Save or unsave a visible Audience | | `update` | `name`, visibility/team-sharing fields as needed | Update supported Audience fields | | `delete` | Explicit confirmation | Delete the Audience | | `add_member` / `remove_member` | `mindId` | Change Audience membership | | `regenerate_images` | Optional `force`, `limit`, `dry` | Regenerate member images or preview the operation | ### manage\_formation For `preview`, both `userInput` and `priorHypothesis` are optional. Blank input uses the default request; text is trimmed and limited to 2000 characters. The forwarded JSON must fit within 64 KiB. MCP validates returned counts, flags, phase and the creation-compatible hypothesis, removes unknown fields, and returns a tool error for malformed responses. Preview does not persist a Formation. For `get`, MCP validates the returned Formation ID and detail fields, removes stored diagnostics, and uses safe failure messages. Malformed or mismatched detail responses return a tool error. Read `status` before using subgroup assignments: recompute can retain the previous completed buckets while building. For `create`, review 2–15 buckets with non-empty text, distinct IDs and distinct labels after trimming. Do not use the reserved IDs `unanswered`, `__unanswered`, or `__other`. `name` is optional. The forwarded JSON must fit within 64 KiB. A user-created split with fewer than two populated primary buckets fails; inspect the returned status before using it. See the [Audience API](https://getminds.ai/docs/api/audiences) for creation errors. All actions require `audienceId`. | Action | Additional inputs | Effect | | ----------- | ----------------------------------------- | -------------------------------------- | | `list` | — | List Formations | | `get` | `formationId` | Read a Formation | | `preview` | `userInput`, `priorHypothesis` (optional) | Return a non-persisted JSON hypothesis | | `create` | `name`, reviewed `hypothesis` | Persist and compute a Formation | | `delete` | `formationId`, explicit confirmation | Delete a Formation | | `recompute` | `formationId` | Recompute assignments | A hypothesis contains `intent` and `subgroups[]` with `id`, `label`, and `definition`. The UI consumes NDJSON progress and this tool requests JSON from the same v1 preview endpoint. ### manage\_study Requires `studyId`. `action: "get"` reads a Study and returns its workspace link. `action: "delete"` requires explicit confirmation and deletes it. The owner can also use `action: "set_link_sharing"` with required boolean `isLinkSharingEnabled`, or `action: "invite"` with 1–100 `emails` and optional `role` (`member`, the default, or `admin`). Enable public sharing only on an explicit user request: attached Audiences and Minds also become publicly readable. The sharing result includes `sharedStudyUrl` when public access is active. Invitation results include `emailFailures`; a successful API response does not guarantee every email was delivered. ### manage\_chat | Action | Required | Effect | | -------------- | ---------------------------------------------------------------------------- | ------------------------------------------ | | `create` | One of `mindId`, `mindIds`, or `audienceIds`; optional `name`, `description` | Create a stateful chat | | `send_message` | `chatId`, `message`; optional `role` | Append a message and get the next response | | `delete` | `chatId`, explicit confirmation | Delete chat history | For a follow-up on an existing Study response, `create` also accepts one `mindId` and `responseThread: { studyId, messageId }`. The server retains the authorized prior context and assets. ### manage\_study\_draft Requires the draft UUID in `draftId`. `action: "delete"` deletes the draft and requires an empty successful API acknowledgement. `action: "consume"` requires a positive `expectedRevision` and accepts an optional Study UUID in `studyId`. It closes planning state; it does not start or verify research. A stale revision is rejected for an active draft; retrying an already consumed draft returns its existing tombstone without changing the linked Study. The tool requires a matching consumed draft response and reports malformed acknowledgements as errors. Check saved state before retrying an uncertain result. ## Deliberate exclusions API credential creation, rotation, and revocation are not exposed through MCP because an MCP session must not control its own bearer credential. Manage keys only in authenticated [account settings](https://getminds.ai/settings/api-keys) or through an independently authenticated REST administration flow. # Minds MCP Operating Guide for AI Agents Tool availability depends on deployment configuration: ordinary discovery exposes 23 tools, or 24 when `list_model_connections` is enabled, with 42 or 43 canonical tools registered respectively. Treat the connected server’s `tools/list` response as authoritative. Use this guide as the behavioral contract for an agent connected to `https://getminds.ai/mcp`. Parameter schemas remain authoritative in MCP `tools/list` or the explicit tool configuration; the [tools reference](https://getminds.ai/mcp/tools) explains the complete canonical surface. ## Surface model - **23–24 advertised tools** are returned by ordinary `tools/list` discovery. - **42–43 canonical tools** are registered across Minds, Audiences, Studies, Formations, knowledge, chat, analytics, and exports. - Additional aliases remain compatibility inputs, not names agents should generate. - Lifecycle tools that are not advertised can be used by explicit integrations capable of calling a configured canonical tool name. - MCP and the first-party UI delegate supported research behavior to the same v1 API/application services. If the client only allows discovered tools, plan around the 23–24 advertised tools. Do not claim that a hidden lifecycle tool was executed when the host could not provide its schema or invoke it. ## Fast routing table | User intent | Tool | Important behavior | | -------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | List existing audiences | `list_audiences` | Use optional fuzzy search | | Check the available Audience size or creation mode | `get_audience_limits` | Read this account’s effective limits before choosing a size | | Import supplied text research sources | `import_audience_sources` | Account-owned source import; creates no Audience | | Create an audience from a population brief or research files | `create_audience_from_brief` | Private by default; safe identical-argument retry | | Inspect a respondent dataset before cohort creation | `preview_audience_dataset_segmentation` | Enterprise workflow; never one Mind per row | | Ask one existing Audience a direct question | `ask_audience` | Creates a private one-Audience Study and submits immediately | | Refresh stored Audience grounding | `recalibrate_audience` | Refreshes grounding and recalibrates affected member profiles; inspect returned progress | | Check an Audience against real, published surveys | `validate_audience`, `get_audience_validation` | Explicit tools, callable by name but not yet in tool discovery; needs at least 10 ready Minds; poll `get_audience_validation` with the returned `batchId` until the run settles | | List/create/ask a multi-Audience Study | `list_studies`, `create_study`, `ask_study` | Poll `get_study_status` after submission | | One direct research question | `ask_study` | Do not create a Study plan unless evidence requirements are broader | | Multiple questions, broad task, asset audit, structured outputs, or named method | `plan_study_questions` | Draft only; present every confirmation question | | Run an exact reviewed plan | `run_study_questions` | Requires explicit confirmation and exact revision | | Poll a Study | `get_study_run` | Preserve partial artifacts and plan-limit status | | Read/refresh semantic evidence summary | `get_study_summary` | `refresh: false` reads; `true` generates/refreshes | | Export existing Study evidence | `export_study` | Do not start new research | | Read/start an existing question’s asset heatmap | `study_heatmap` | Start consumes allowance; reuse the assigned asset and inspect status | | Inspect team model connection choices | `list_model_connections` | Read verified selection metadata; no credentials | | Inspect analytics | `get_study_analytics` | Preserve response-type semantics | | Resume sidebar planning state | `list_study_drafts`, `save_study_draft` | Use exact optimistic revision | | Create/chat with/export a Mind | `create_mind`, `chat_with_mind`, `export_mind` | Poll `get_mind_status` after creation | | Explicit resource lifecycle work | `manage_*` tools | Confirm destructive actions; see action matrices | ## Planning and consent boundary For guided research, follow this exact sequence: ```text plan_study_questions -> show the captured objective, main source, questions, methods, and outputs -> ask every returned confirmation question -> call plan_study_questions again with answers/refinements -> obtain explicit confirmation of the exact draft ID and revision -> run_study_questions with confirmed: true -> poll get_study_run -> read or refresh get_study_summary ``` Rules: - A planning response is not an executed Study. - A questionnaire, survey, battery, section, or any set of two or more known questions belongs in one plan and one confirmed run. Organize related questions into named modules when useful; never iterate one tool call per question. - Silence, an unanswered question, or the agent's own recommendation is not consent. - Any user change creates/requires a new revision; reconfirm that revision. - Only methods returned with `executable: true` can be promised as runnable. - Advanced methods require explicit opt-in. - An export or alternative presentation of existing evidence does not require new respondents. ## Confirmation policy Require explicit confirmation immediately before: - deleting a Mind, Audience, Study, Formation, chat, knowledge item, or Study draft; - batch deletion, with the complete set of Mind IDs shown; - enabling public/link sharing when the user did not already request it; - consuming a Study draft revision when that changes workflow state; - any other tool/result that returns a confirmation requirement. Creating a private resource, reading state, checking status, or running the exact Study revision the user just explicitly approved does not need a second invented confirmation. ## Privacy and sharing - New Audiences and Studies are private unless `isLinkSharingEnabled: true` is passed. - Set that flag only when the user explicitly requests a public/shareable link. - A shared Audience can expose its persisted grounding, distributions, source metadata, and supported research context. - For external handoff, use only a shared link returned by the tool. - A workspace link is for the authenticated creator; it is not proof that an external recipient has access. - Never add collaborators, invite accounts, or claim an object was added to someone else's account unless the user explicitly requests account collaboration and a supported tool performed it. ## Names, IDs, and active-session context - Prefer an exact ID after any successful create/list/resolve call. - Fuzzy-name parameters are for natural user references, not durable automation state. - `ask_audience`, `get_audience`, `recalibrate_audience`, `validate_audience`, `get_audience_validation`, and `list_formations` can resolve an Audience name directly. Do not insert a redundant list call solely for lookup. - Study tools may use the active Study from the MCP session when both ID and name are omitted. For durable/multi-user automation, pass the explicit `studyId`. - Persist `draftPlanId`, `revision`, `studyId`, `draftId`, `expectedRevision`, and export/job identifiers returned by tools. ## Polling and terminal state | Operation | Status tool | Terminal handling | | ------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------- | | Mind creation/training | `get_mind_status` | Chat only when ready; report failure details | | Direct Audience/Study question | `get_study_status` | Present aggregated and individual answers when complete | | Guided Study | `get_study_run` | Preserve immutable plan, method calculations, and artifacts | | Export | `export_study` then returned status/link; optionally `get_study_status` | Present artifact only when ready | | Knowledge ingestion | `manage_mind_knowledge` with `action: "status"` | Do not assume uploaded means processed | | Audience creation | `manage_audience` with `action: "get_progress"` when explicitly available | Report settled progress, not guessed elapsed-time progress | The MCP widget is a view of returned evidence, not the execution authority. It consumes host snapshots and, on the supported consent-free host bridge, automatically checks status at a bounded interval. Standard hosts may require a user-triggered Refresh. Automatic polling can stop after a limit or error; this does not mean the Study completed. Poll the existing Study with its exact ID or preserve its returned workspace link. Do not rerun research to repair a stale display. Mobile widgets display a Minds handoff link without starting the interactive controller or polling. Tool availability is still governed by the host; never claim the MCP server is disabled on mobile. The plan widget displays the saved review text; request revisions in conversation and confirm the latest version before execution. It has no execution button. Preserve all returned questions, Audience aggregates, individual answers, and response coverage. `partial` is terminal but incomplete. A 100% settled-question count does not prove full respondent participation. Inspect `outputData.responseCoverage` where available; historical artifacts without coverage cannot prove full participation. Use bounded exponential backoff and respect any retry hint. A tool timeout is an unknown outcome, not proof that the mutation failed. ## Retry rules - Read-only calls are safe to retry after transient transport failure. - `create_audience_from_brief` is idempotent for identical arguments. Retry the exact same payload after a timeout to recover the original Audience. - To intentionally create another Audience from the same brief within the idempotency window, change a meaningful argument such as `name`. - Preserve and reuse explicit idempotency keys returned/accepted by Study execution. - Before retrying a destructive or non-idempotent lifecycle action, read current state. - Never “fix” a failed tool call by switching to a different resource found through fuzzy matching. ## Files and external URLs - Tool-call payloads should reference files using public, short-lived signed, or Minds workspace-upload URLs. - Do not embed large base64 binaries in MCP arguments. - Supply `name`, `url`, and `type` when known. - A syntactically valid URL can still be rejected by security checks. - Mind knowledge files are limited to 50 MB and enter the same processing queue as UI multipart uploads. - `preview_audience_dataset_segmentation` accepts CSV/XLS/XLSX respondent data and returns variables for review; it does not create one Mind per respondent. - Screeners and questionnaire programming grids are design evidence, not respondent datasets. Pass them to `create_audience_from_brief` instead of forcing segmentation preview. ## Plan and error semantics | Result | Agent behavior | | ------------------------------------------------ | ----------------------------------------------------------------------------- | | Authentication required | Ask the user to reconnect OAuth or configure a bearer API key; do not loop | | Resource not found | Verify exact ID/account context; do not silently substitute a fuzzy match | | Validation error | Correct the named field and call again only if user intent is unchanged | | `plan_limited` returned by `run_study_questions` | Nothing started; explain that an upgrade/allowance change is required | | `status: plan_limited` from `get_study_run` | Partial artifacts exist; report completed and remaining questions | | Method has `executable: false` | Explain it is represented/planned and offer executable alternatives/fallbacks | | Tool returns `isError: true` | Do not present success text or fabricate structured content | | Ambiguous fuzzy match | Present candidates and ask the user to choose | ## Output presentation contract - Preserve every returned URL verbatim. - Preserve citations and evidence links; do not replace them with unsourced summaries. - In text-only clients, retain Study question headings, bold Audience aggregates, and individual Mind-answer bullets returned by the tool. - Clearly distinguish synthetic research from primary human respondent research. - Never claim queued, partial, failed, cancelled, or plan-limited work is complete. - Do not expose internal bearer tokens, storage paths, hidden prompts, or private links. - If a widget renders, structured/text content still remains the accessibility and compatibility fallback. ## Safe lifecycle action patterns ### Delete several Minds 1. Resolve and show the exact Mind names and IDs. 2. Ask for explicit confirmation of that set. 3. Call `manage_mind` with `action: "delete_many"` and `mindIds`. 4. Report deleted, skipped, and failed items separately. ### Add file knowledge 1. Confirm the target `mindId`. 2. Obtain a public/signed/workspace upload URL. 3. Call `manage_mind_knowledge` with `action: "add"` and `file`. 4. Persist the returned item ID. 5. Poll the same tool with `action: "status"` before saying the knowledge is ready. ### Preview and create a Formation 1. Call `manage_formation` with `action: "preview"`, `audienceId`, and the user's `userInput`. 2. Present the returned intent and subgroups for review. 3. If changed, preview again with `priorHypothesis`. 4. Create only the reviewed hypothesis with `action: "create"`. ## Agent preflight Before any tool call, ask internally: - Is this the correct resource type: Mind, Audience, Study, draft, or Formation? - Is the request one direct question or a broader Study? - Does the tool read, mutate, consume allowance, expose publicly, or delete? - Do I have an exact ID or a supported fuzzy-name parameter? - Could a prior timeout already have created or changed the resource? - Does the user need to confirm an exact revision or destructive target? - What status tool proves completion? After the call, inspect `isError`, preserve structured identifiers, and describe only the state the server actually returned.