---
title: "API Overview"
description: "Introduction to the Minds v1 API for programmatic Minds, Audiences, Studies, knowledge, chat, analytics, and export workflows."
---

# 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](/settings/api-keys).

Include your API key in the `Authorization` header:

```bash
Authorization: Bearer minds_your_api_key_here
```

### OpenAPI Spec

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

### Content Type

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

```bash
Content-Type: application/json
```

For file uploads, use:

```bash
Content-Type: multipart/form-data
```

## Capability overview

This overview highlights the primary workflows. The [v1 endpoint catalog](/docs/api/reference) 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:

```bash
# 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](/docs/api/authentication)
- Browse the [complete v1 endpoint catalog](/docs/api/reference)
- Read the [API integration guide for agents](/docs/api/agents)
- Explore [Minds endpoints](/docs/api/minds)
- Read about [Knowledge management](/docs/api/knowledge)
- Understand [Chat completions](/docs/api/chat)
- Create [Studies](/docs/api/studies) for multi-Mind surveys
- Review [Latency & Performance](/docs/api/latency)
- Connect via [MCP Integration](/mcp/overview)
- Review [Errors & Limits](/docs/api/errors)

## 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.

:plan-limits-table[View Plans](/settings?tab=subscription)

## Need Help?

If you have questions or need support with the API:

- Check our [Guide](/guide)
- Contact us through the feedback form
- Join our community discussions