Minds v1 API Endpoint Catalog

This catalog lists the complete customer-facing v1 route surface. Use it with the live OpenAPI 3.1 document for schemas and the agent integration guide 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.
• {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

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.

Batch deletion accepts:

{
  "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

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

{
  "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

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

Audience Formations

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

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

Studies, analytics, and exports

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.

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

Durable Study drafts

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

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

Stateful chats

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, Audiences, Studies, Knowledge, and Chat
• Authentication and key rotation: Authentication
• Errors, plan limits, and retry policy: Errors & Limits
• Autonomous integrations: API guide for agents
• Tool-native integrations: MCP tools reference