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.

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.

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

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:

# 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
• Browse the complete v1 endpoint catalog
• Read the API integration guide for agents
• Explore Minds endpoints
• Read about Knowledge management
• Understand Chat completions
• Create Studies 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 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.

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