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}, {sparkId}, {panelId}, 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:

{
  "sparkIds": [
    "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.

Groups and grounding

Groups and Panels 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.

Group Formations

A Formation is a persisted segmentation of one Group 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.

Panels, analytics, and exports

Composite creation through groupConfigs is atomic: if any inline Group fails, the operation rolls back the Panel and Groups created by that request.

Guided Studies and durable runs

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, Groups, Panels, 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