API Overview

The Minds v1 API exposes supported programmatic workflows for Minds, Groups, Panels, Studies, knowledge, chat, analytics, and exports. In route names, a Mind is represented by the historical resource name spark; customer-facing responses and documentation use Mind.

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 or https://api.getminds.ai/v1

Local Development: http://localhost:3000/api/v1

Both production base URLs are fully equivalent. The api.getminds.ai subdomain is recommended for cleaner integration URLs.

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.

Include your API key in the Authorization header:

Authorization: Bearer minds_your_api_key_here

OpenAPI Spec

A machine-readable OpenAPI 3.1.0 spec is published at /_openapi.json. Use it for typed client generation and combine it with the complete endpoint catalog for v1 routes whose detailed OpenAPI schemas are still being expanded. Agents should also read the API integration guide for agents.

Content Type

All requests that send data should include the Content-Type header:

Content-Type: application/json

For file uploads, use:

Content-Type: multipart/form-data

Capability overview

This overview highlights the primary workflows. The v1 endpoint catalog lists every customer-facing route, including lifecycle, progress, Formation, durable-run, Study-draft, analytics, and export helpers.

Sparks

Create and manage AI minds (agents) with custom configurations.

GET /api/v1/sparks - List all sparks
GET /api/v1/sparks/library - List the authenticated user's owned and shared Mind library projection
GET /api/v1/sparks/{sparkId} - Get spark details
POST /api/v1/sparks - Create a new spark
PUT /api/v1/sparks/{sparkId} - Update a spark
DELETE /api/v1/sparks/{sparkId} - Delete a spark
DELETE /api/v1/sparks - Batch-delete confirmed sparks with the same file and telephony cleanup as single delete
POST /api/v1/sparks/{sparkId}/regenerate-prompt - Regenerate system prompt from knowledge
GET /api/v1/sparks/{sparkId}/patterns - Get raw thinking patterns for a spark

Groups

Create and manage Audiences (Groups) used by Panels.

GET /api/v1/groups - List visible Groups
GET /api/v1/groups/library - List the first-party owned and shared Group library projection
POST /api/v1/groups - Create a Group
GET /api/v1/groups/{groupId} - Get Group details
PUT /api/v1/groups/{groupId} - Update a Group
DELETE /api/v1/groups/{groupId} - Delete a Group
POST /api/v1/groups/{groupId}/follow - Save a public Group
DELETE /api/v1/groups/{groupId}/follow - Remove a saved public Group
GET /api/v1/groups/{groupId}/progress - Read settled Group build progress
POST /api/v1/groups/{groupId}/formations/preview - Preview a Formation as NDJSON or JSON

Knowledge

Manage knowledge for your minds.

GET /api/v1/sparks/{sparkId}/knowledge - List knowledge items
POST /api/v1/sparks/{sparkId}/knowledge - Add knowledge (links, files, or keyword search)
PUT /api/v1/sparks/{sparkId}/knowledge/{itemId} - Update a knowledge item
DELETE /api/v1/sparks/{sparkId}/knowledge/{itemId} - Delete a knowledge item
POST /api/v1/sparks/{sparkId}/knowledge/enrich - Enrich via keyword search (convenience alias)
GET /api/v1/sparks/{sparkId}/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 Panel chat
POST /api/v1/chats/{chatId}/messages - Continue a stateful chat
DELETE /api/v1/chats/{chatId} - Delete a stateful chat
POST /api/v1/sparks/{sparkId}/completion - Send messages and get responses

Panels

Create and manage AI panels for surveying groups of minds.

GET /api/v1/panels - List all panels
POST /api/v1/panels - Create a new panel
GET /api/v1/panels/{panelId} - Get panel details with message history
DELETE /api/v1/panels/{panelId} - Delete a panel
POST /api/v1/panels/{panelId}/ask - Ask a question to all panel minds (SSE stream)
GET /api/v1/panels/{panelId}/analytics - Compute panel analytics
POST /api/v1/panels/{panelId}/research-plans/preview - Create or revise a research-plan draft
POST /api/v1/panels/{panelId}/studies - Confirm and start an exact plan revision
GET /api/v1/panels/{panelId}/studies/{studyId} - Poll durable Study status
POST /api/v1/panels/{panelId}/runs - Start a durable direct run
GET /api/v1/panels/{panelId}/runs - List durable runs
GET|POST /api/v1/panels/{panelId}/summary - Read or refresh the semantic summary
POST /api/v1/panels/{panelId}/export - Export panel results as report
GET /api/v1/panels/{panelId}/export-status - Check export job status
GET /api/v1/panels/{panelId}/export-download - Download exported PDF

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:

# 1. Create a mind (keywords mode)
curl -X POST "https://getminds.ai/api/v1/sparks" \
  -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": "spark-id", ... }, "processing": { "queued": true, ... } }

# 2. Create a mind from social profile (clone mode)
curl -X POST "https://getminds.ai/api/v1/sparks" \
  -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/sparks/spark-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
Browse the complete v1 endpoint catalog
Read the API integration guide for agents
Explore Sparks endpoints
Read about Knowledge management
Understand Chat completions
Create Panels for multi-mind surveys
Review Latency & Performance
Connect via MCP Integration
Review Errors & Limits

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 Panel sessions draw on the applicable chat or response allowance. The Individual plan is represented as "premium" in API payloads.

View Plans

Need Help?

If you have questions or need support with the API:

Check our Guide
Contact us through the feedback form
Join our community discussions