---
title: "Minds API"
description: "Create and manage AI minds programmatically with custom configurations and personalities. Covers creating, listing, updating, and deleting minds."
---

# Minds API

Create and manage AI minds (agents) programmatically. Minds are customizable AI assistants with specific expertise, personalities, and knowledge.

**Base URL:** `https://getminds.ai/api/v1` or `https://api.getminds.ai/v1`

## Get Mind

Retrieve a single mind with full details including system prompt, sharing settings, and knowledge item count.

**Endpoint:** `GET /api/v1/minds/{mindId}`

### Access

Readable Minds are the ones you own, Minds shared with you directly or with your team, Minds inside an Audience you own, belong to, or that is shared with your team, Minds inside a Study you belong to, and public Minds. Anything else returns `403 Access denied`. The `systemPrompt` is only included when you own the Mind, collaborate on it, share it through your team, or belong to a private Audience that contains it; public visibility alone never exposes it.

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Life Story & Background\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}
```

### Response Fields

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Unique mind identifier
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind description
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
      , or <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Area of expertise
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Full system prompt defining the mind's behavior
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Categorization tags
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Whether the mind is publicly accessible
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLinkSharingEnabled
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Whether link sharing is enabled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicShareId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Share ID for public access (null if not shared)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Avatar image URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phoneNumber
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Associated phone number (null if none)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clonedVoiceStatus
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Voice cloning status (null if not cloned)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profitSplitOptIn
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Whether profit split is enabled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        knowledgeItemCount
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Number of knowledge items attached
    </td>
  </tr>
</tbody>
</table>

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Error Responses

**400 Bad Request** - Invalid mind ID format

**401 Unauthorized** - Invalid or missing API key

**403 Forbidden** - No access to this mind (see **Access** above)

**404 Not Found** - Mind doesn't exist

---

## List Minds

Retrieve the Minds you own. Minds that are only shared with you — directly, through your team, or through an Audience or Study — are **not** included here; list those with the [library projection](#library-projection) below.

**Endpoint:** `GET /api/v1/minds`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Query Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Filter minds by name, description, or discipline (case-insensitive)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      100
    </td>
    
    <td>
      Maximum number of minds to return (1–100)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      0
    </td>
    
    <td>
      Number of minds to skip for pagination
    </td>
  </tr>
</tbody>
</table>

### Response

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}
```

### Response Fields

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Array of mind objects
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Total number of minds matching the query
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Maximum results per page
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      Number of results skipped
    </td>
  </tr>
</tbody>
</table>

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Library projection

`GET /api/v1/minds/library` returns every Mind you can open, with the caller's effective role: Minds you own, Minds shared with you directly or with your team, and Minds reached through an Audience you own, belong to, or that is shared with your team, or through a Study you belong to. It is the canonical endpoint used by the Minds UI and the right starting point when Minds were delivered to your team rather than created by you. Fields that could reveal private configuration are omitted when the caller does not have a member role.

## Create Mind

Create a new AI mind with custom configuration using different training modes.

**Endpoint:** `POST /api/v1/minds`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

```json
{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg",
  "sourcePolicy": "knowledge_only"
}
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Yes
      </strong>
    </td>
    
    <td>
      Name of the mind (2-100 characters)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        Yes
      </strong>
    </td>
    
    <td>
      The mind's area of expertise (e.g., "Marketing", "Engineering")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mode
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Training mode: <code>
        keywords
      </code>
      
      , <code>
        clone
      </code>
      
      , <code>
        link
      </code>
      
      , or <code>
        manual
      </code>
      
      . Default: <code>
        keywords
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Type of mind: <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
      , or <code>
        user
      </code>
      
      . Default: <code>
        expert
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Description of the mind's purpose
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Conditional
    </td>
    
    <td>
      Array of keywords (required if <code>
        mode
      </code>
      
       is <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        personaContext
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Conditional
    </td>
    
    <td>
      Name/context of the person to emulate (required if <code>
        mode
      </code>
      
       is <code>
        clone
      </code>
      
      ; also used to derive keywords automatically)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contextLink
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Conditional
    </td>
    
    <td>
      URL to profile/content (required if <code>
        mode
      </code>
      
       is <code>
        link
      </code>
      
      ; the server scrapes it to derive keywords)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Array of tags for categorization (max 20 tags)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      External URL to avatar image (will be downloaded and stored)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Auto-training modes generate an AI profile image by default; set <code>
        false
      </code>
      
       to opt out
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        includeWebSearch
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Defaults to <code>
        true
      </code>
      
      . Set <code>
        false
      </code>
      
       to skip automatic web research. For a strictly private source-only Mind, use <code>
        mode: "manual"
      </code>
      
      , upload its knowledge, wait for processing, and regenerate the prompt. Cannot be combined with <code>
        mode: "link"
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sourcePolicy
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Persisted answer policy: <code>
        auto
      </code>
      
       (default) or <code>
        knowledge_only
      </code>
      
      . A knowledge-only Mind always retrieves processed Mind knowledge and returns <code>
        409 KNOWLEDGE_SOURCE_UNAVAILABLE
      </code>
      
       instead of guessing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cloneVoice
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      When <code>
        true
      </code>
      
      , triggers voice cloning via YouTube search (experimental)
    </td>
  </tr>
</tbody>
</table>

### Mode Values

The `mode` parameter determines how your mind will be trained:

- **keywords** (default) - Train your mind using comma-separated keywords. The AI will gather relevant information from various sources based on these keywords to build the mind's knowledge base.
  - **Required field:** `keywords` - Array of keywords/topics
  - **Best for:** General expertise on specific topics or domains
- **clone** - Clone a person's style and knowledge by providing their name and context. The AI will research and build a comprehensive profile mimicking their expertise and communication style.
  - **Required field:** `personaContext` - Name and brief context (e.g., "Ada Lovelace, pioneering computer scientist")
  - **Best for:** Emulating specific individuals, historical figures, or well-known experts
- **link** - Train your mind using content from a specific URL. Provide a link to a profile, portfolio, or website, and the AI will analyze and extract relevant information.
  - **Required field:** `contextLink` - URL to the content source
  - **Best for:** Training on specific websites, portfolios, or online profiles
- **manual** - Create a mind without automatic training. You'll manually configure all settings and add knowledge later through the knowledge API.
  - **No additional fields required**
  - **Best for:** Custom configurations where you want full control over the training data

> **Auto-processing:** When you use `keywords`, `clone`, or `link`, the backend mirrors the in-product Add Mind form — it derives entity keywords (AI-assisted for `clone`/`link`) and trains the mind asynchronously. Track that training through the `training` block on the create response and the dedicated endpoint described in **Mind training lifecycle** below. `manual` mode skips this automation so you can train the mind later via the Knowledge API.

### Type Values

- **creative** - For artists, designers, writers, and creative professionals
- **expert** - For specialists, consultants, and domain experts
- **user** - For user personas, customers, and target audience archetypes

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}
```

The `training` block reports the mind's lifecycle at creation. `keywords`, `clone`, and `link` modes start `queued` and train in the background; `manual` minds come back `completed` with `readyToChat` already `true`. A mind's `id` exists the moment this call returns, but the mind can only answer once `readyToChat` is `true`. See **Mind training lifecycle** below for how to poll.

### Example: Create Mind with Keywords Mode

```bash
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": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'
```

### Example: Create Mind with Clone Mode

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'
```

### Example: Create Mind with Link Mode

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'
```

### Example: Create Mind with Manual Mode

```bash
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'
```

## Mind training lifecycle

Creating a mind is asynchronous. `POST /v1/minds` returns immediately with an `id`, but for the `keywords`, `clone`, and `link` modes the mind is still being trained in the background. **A mind's id existing does not mean the mind is ready** — the mind can only answer once `readyToChat` is `true`. The one exception is `manual` mode: those minds skip data collection and are `completed` the moment they are created.

Poll the dedicated training endpoint until the mind is ready:

```bash
curl "https://getminds.ai/api/v1/minds/{mindId}/training" \
  -H "Authorization: Bearer minds_your_api_key"
```

```json
{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}
```

### Status values

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
    
    <th>
      <code>
        readyToChat
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        queued
      </code>
    </td>
    
    <td>
      Training is enqueued but has not started yet.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        running
      </code>
    </td>
    
    <td>
      The mind is actively collecting knowledge and building its persona.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        completed
      </code>
    </td>
    
    <td>
      Training finished. The mind is ready to chat.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        failed
      </code>
    </td>
    
    <td>
      Training did not finish. Inspect <code>
        error
      </code>
      
       and retrain if it is retryable.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

`GET /v1/minds/{id}` also returns `readyToChat` (and `trainingStatus`) alongside the rest of the mind, so a single read tells you both who the mind is and whether it can answer yet.

### When training fails

When `status` is `failed`, the response includes an `error` object with a `code` and a `retryable` flag:

<table>
<thead>
  <tr>
    <th>
      Error code
    </th>
    
    <th>
      Meaning
    </th>
    
    <th>
      <code>
        retryable
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        COLLECTION_FAILED
      </code>
    </td>
    
    <td>
      Knowledge collection could not complete.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROFILE_GEN_FAILED
      </code>
    </td>
    
    <td>
      The persona profile could not be generated.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMEOUT
      </code>
    </td>
    
    <td>
      Training exceeded its time budget and was stopped.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INTERNAL
      </code>
    </td>
    
    <td>
      An unexpected internal error occurred.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

### Retraining

If a mind ends in `failed` (or you simply want to rebuild a `completed` mind), retrain it:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"
```

This re-queues the mind and returns a fresh `training` block with `status` set to `queued`. Retrain only works on minds that have finished: a mind that is still `queued` or `running` returns `409 Conflict` because a training run is already in flight. After retraining, poll `GET /v1/minds/{id}/training` again until `readyToChat` is `true`.

## Profile Images

When you provide a `profileImageUrl`:

1. The image is downloaded from the external URL
2. Uploaded to secure storage
3. The stored URL is returned in the response

Supported formats: JPG, PNG, GIF, WEBP

## How Training Works

The system automatically generates an intelligent system prompt based on your chosen mode, type, and discipline:

- **Keywords mode**: Creates expertise around your specified keywords
- **Clone mode**: Builds a profile emulating the specified person's style and knowledge
- **Link mode**: Extracts knowledge from the provided URL
- **Manual mode**: Creates a basic assistant that you'll train with custom knowledge

You can further enhance your mind by [uploading knowledge](/api/knowledge) after creation.

## Plan Limits

See the generated [plan-limit table](/api/overview) for current public defaults. Account-specific contract overrides may differ; integrations should use `data.limit` and `data.current` from an authenticated `PLAN_LIMIT` response. The Individual plan is represented as `"premium"` in API payloads.

When you reach your limit, you'll receive a `403 Forbidden` error:

```json
{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "minds",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}
```

Branch on `data.code` and `data.limitType` rather than on the message wording.

## Error Responses

### 400 Bad Request

Missing or invalid parameters.

```json
{
  "statusCode": 400,
  "statusMessage": "Name is required"
}
```

### 401 Unauthorized

Invalid or missing API key.

### 403 Forbidden

Plan limit reached.

### 500 Internal Server Error

Server-side error (rare).

## Update Mind

Update an existing mind's configuration, including name, description, system prompt, and other settings.

**Endpoint:** `PUT /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### Request Body

```json
{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "sourcePolicy": "knowledge_only",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Name of the mind (2-100 characters)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Description of the mind's purpose
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Type: <code>
        creative
      </code>
      
      , <code>
        expert
      </code>
      
      , or <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      The mind's area of expertise
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Custom system prompt that defines the mind's behavior and personality
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sourcePolicy
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Persisted answer policy: <code>
        auto
      </code>
      
       or <code>
        knowledge_only
      </code>
      
      . A request-level chat or panel setting cannot downgrade a knowledge-only Mind.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Array of tags for categorization (max 20 tags)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Whether the mind is publicly accessible
    </td>
  </tr>
</tbody>
</table>

### System Prompt

The `systemPrompt` field allows you to customize how your mind behaves and responds. This is useful for:

- **Persona customization**: Define specific personality traits, communication style, or expertise areas
- **Response formatting**: Instruct the mind to respond in specific formats (e.g., bullet points, numbered lists)
- **Domain constraints**: Limit responses to specific topics or perspectives
- **Language/tone**: Set the language, formality level, or tone of responses

**Example system prompts:**

```text
# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.
```

```text
# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.
```

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "sourcePolicy": "knowledge_only",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}
```

### Example: Update System Prompt

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'
```

### Example: Update Multiple Fields

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'
```

### Error Responses

**400 Bad Request** - No valid fields to update or invalid field values

**401 Unauthorized** - Invalid or missing API key

**403 Forbidden** - No permission to update this mind (you must be the owner)

**404 Not Found** - Mind doesn't exist

## Get Mind Patterns (Raw)

Retrieve the raw `Pattern[]` rows for a mind. This is the unprocessed feed used by the SphereGraph visualization in the product UI — it returns one row per detected pattern (method/competency pair plus the supporting `mind` quote and source linkage), without any framework grouping or aggregation.

If you want the structured, framework-grouped view, use the `Get Mind Knowledge Patterns` endpoint below instead.

**Endpoint:** `GET /api/v1/minds/{mindId}/patterns`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

```json
{
  "data": [
    {
      "id": 12345,
      "mindId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "...",
      "messageId": null,
      "portfolioItemId": "abc-123",
      "aspect": "Strategic Thinking",
      "subAspect": "Market Analysis",
      "mind": "Market segmentation requires understanding customer pain points...",
      "isPredefined": true,
      "isPredefinedAspect": true,
      "isPredefinedSubAspect": true,
      "createdAt": "2025-12-10T15:30:00.000Z"
    }
  ]
}
```

Results are ordered by `createdAt` descending. The legacy field names `aspect`/`subAspect` correspond to the `method`/`competency` columns in the underlying schema and are preserved for backward compatibility.

### Access Rules

- Public minds (`isPublic: true`) and link-shared minds (`publicShareId` set) are readable without authentication.
- Private minds require an API key whose owner is the mind owner, a team member, or a direct member.

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/patterns" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Error Responses

**400 Bad Request** - Invalid mind ID format

**401 Unauthorized** - Mind is private and no valid API key was supplied

**403 Forbidden** - No access to this private mind

**404 Not Found** - Mind doesn't exist

---

## Get Mind Knowledge Patterns

Retrieve thinking patterns and knowledge organized by framework for a specific mind.

**Endpoint:** `GET /api/v1/minds/{mindId}/knowledge/patterns`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response Structure

The endpoint returns patterns grouped by frameworks (e.g., AOX Internal, OCEAN, DISC, etc.), with methods and competencies showing occurrences and evidence.

```json
{
  "success": true,
  "data": {
    "mindId": "550e8400-e29b-41d4-a716-446655440000",
    "mindName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "mind": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "mind": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### Understanding the Response

- **frameworks**: Array of frameworks containing the mind's patterns

  - **totalOccurrences**: Total number of patterns in this framework
  - **methods**: Thinking methods or approaches detected
  
    - **occurrences**: Number of times this method appears
    - **competencies**: Specific skills or sub-areas within the method
    
      - **occurrences**: Number of patterns for this competency
      - **evidence**: Array of citations/quotes demonstrating this pattern
      
        - **mind**: The actual quote or insight from the content
        - **portfolioItemId**: Reference to the source material
        - **createdAt**: When this pattern was identified

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Use Cases

- **Understanding mind expertise**: See what methods and competencies your mind has learned
- **Quality assurance**: Verify patterns are being extracted correctly from training data
- **Knowledge gaps**: Identify areas where more training data is needed
- **Framework comparison**: Compare how a mind performs across different frameworks

### Error Responses

**401 Unauthorized** - Invalid or missing API key

**403 Forbidden** - No access to this mind

**404 Not Found** - Mind doesn't exist

## Regenerate System Prompt

Regenerate all system prompt components for a mind using its existing knowledge base. This uses the same AI-powered generation as the UI's "Generate All" button.

**Endpoint:** `POST /api/v1/minds/{mindId}/regenerate-prompt`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### How It Works

The endpoint analyzes the mind's knowledge base (portfolio items, patterns, embeddings) and generates a unified set of biographical prompt components for **all** mind types (`user`, `expert`, `creative`):

- **Life Story & Background** — biographical grounding, current age, location, ethnicity, formative experiences
- **Communication & Language** — distinctive voice, phrases, dialect, emotional triggers
- **Knowledge & Experience** — what they know and how they came to know it
- **Values & Contradictions** — beliefs, ideals, and the tensions between them
- **Daily Reality & Context** — economic, temporal, social, and physical context

The `type` field is preserved on the mind for backward compatibility but no longer changes which components are generated. A mind is a mind — the unified biographical approach produces stronger, more grounded personas regardless of type.

### Response

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Mind",
    "systemPrompt": "## Life Story & Background\n\n...",
    "promptLength": 2847
  }
}
```

### Example Request

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Use Cases

- **After adding knowledge**: Regenerate the prompt to incorporate newly added knowledge items
- **Persona refinement**: Regenerate to update the persona based on current knowledge patterns
- **Reset customizations**: Clear manual edits and regenerate fresh prompts from the knowledge base

### Error Responses

**401 Unauthorized** - Invalid or missing API key

**403 Forbidden** - No permission to modify this mind (you must be the owner)

**404 Not Found** - Mind doesn't exist

**500 Internal Server Error** - Failed to generate prompt (e.g., insufficient knowledge)

## Delete Mind

Permanently delete a mind and all associated data including knowledge, portfolio items, and files.

**Endpoint:** `DELETE /api/v1/minds/{mindId}`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### Response

Returns `204 No Content` with an empty body on success.

### Example Request

```bash
curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}" \
  -H "Authorization: Bearer minds_your_api_key"
```

### What Gets Deleted

When you delete a mind, the following are permanently removed:

- The mind itself and all configuration
- All knowledge and training data
- All portfolio items and associated files
- All chat history and messages
- Profile images and uploaded files

**Warning:** This action cannot be undone.

To delete several confirmed Minds with identical cleanup semantics, send
`DELETE /api/v1/minds` with a JSON body:

```json
{ "mindIds": ["mind-uuid-1", "mind-uuid-2"] }
```

The response reports `deleted`, `failed`, and `notFound` IDs independently so
one failure does not conceal the outcome of the remaining deletions.

### Error Responses

**400 Bad Request** - Invalid mind ID format

**401 Unauthorized** - Invalid or missing API key

**403 Forbidden** - No permission to delete this mind (you must be the owner)

**404 Not Found** - Mind doesn't exist

## List Shareable Minds

Retrieve the minds you own that are already shareable — public, or with link sharing enabled. This is the listing that backs share pickers such as the embed-widget settings, where you need to know which minds can be handed to someone else.

**Endpoint:** `GET /api/v1/user/shareable-minds`

### Query Parameters

- **includePrivate** (boolean, default `false`) — pass `true` to also return private minds you own. Selecting a private mind does not make it shareable on its own; you still have to enable sharing on it.
- **limit** (number, default `100`, max `100`) — how many minds to return.
- **offset** (number, default `0`) — how many minds to skip, for paging.

Results are ordered by most recently updated first.

### Response

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Dr. Sarah Chen",
      "type": "expert",
      "discipline": "Behavioral Economics",
      "profileImageUrl": "https://getminds.ai/images/minds/550e8400.webp",
      "publicShareId": "sarah-chen-a1b2c3",
      "isPublic": true,
      "isLinkSharingEnabled": false
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0
  }
}
```

`publicShareId` is the slug used in a mind's public URL. `isPublic` and `isLinkSharingEnabled` tell you *why* a mind is shareable: listed publicly, or reachable by anyone holding the link.

### Example Request

```bash
curl -X GET "https://getminds.ai/api/v1/user/shareable-minds?includePrivate=true&limit=25" \
  -H "Authorization: Bearer minds_your_api_key"
```

### Error Responses

**401 Unauthorized** - Invalid or missing API key

## Next Steps

- [Upload knowledge to your mind](/api/knowledge)
- [Chat with your mind](/api/chat)
- Learn about [errors and limits](/api/errors)