API Overview

Welcome to the Minds API documentation. Our API allows you to programmatically create and manage AI minds, upload knowledge, and interact with them.

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 API endpoints require authentication via API key. You can generate and manage your API keys in your Account Settings.

Include your API key in the Authorization header:

Authorization: Bearer minds_your_api_key_here

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

Available Endpoints

Sparks

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

• GET /api/v1/sparks - List all sparks
• 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
• 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

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/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
• POST /api/v1/panels/{panelId}/ask - Ask a question to all panel minds (SSE stream)
• 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
• 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 usage is subject to your subscription plan:

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