---
title: "Minds API"
description: "以编程方式创建和管理带有自定义配置与人格的 AI mind。"
---

# Minds API

以编程方式创建和管理 AI Minds(agent)。Minds 是具备特定专长、个性与知识的可定制 AI 助手。

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

## 获取 Mind

获取单个 mind 的完整详情,包含 system prompt、共享设置以及知识条目数量。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### 响应

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\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
  }
}
```

### 响应字段

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      唯一 mind 标识符
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind 名称
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind 描述
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        creative
      </code>
      
      、<code>
        expert
      </code>
      
       或 <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      专业领域
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      定义 mind 行为的完整 system prompt
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      分类标签
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Mind 是否公开可访问
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isLinkSharingEnabled
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      是否启用链接分享
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publicShareId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      公共访问的分享 ID(未分享时为 null)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      头像图片 URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        phoneNumber
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      关联手机号(无则为 null)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clonedVoiceStatus
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      语音克隆状态(未克隆则为 null)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profitSplitOptIn
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      是否启用分润
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        knowledgeItemCount
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      已关联的知识条目数量
    </td>
  </tr>
</tbody>
</table>

### 请求示例

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

### 错误响应

**400 Bad Request** - mind ID 格式无效

**401 Unauthorized** - API key 无效或缺失

**403 Forbidden** - 无权访问此 mind

**404 Not Found** - Mind 不存在

---

## 列出 Mind

获取已认证用户拥有的所有 mind。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### 查询参数

<table>
<thead>
  <tr>
    <th>
      参数
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      —
    </td>
    
    <td>
      按名称、描述或领域过滤 mind(不区分大小写)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      100
    </td>
    
    <td>
      返回的最大 mind 数量(1–100)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      0
    </td>
    
    <td>
      分页跳过的 mind 数量
    </td>
  </tr>
</tbody>
</table>

### 响应

```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
  }
}
```

### 响应字段

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Mind 对象数组
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      匹配查询的 mind 总数
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.limit
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      每页最大结果数
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pagination.offset
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      已跳过的结果数
    </td>
  </tr>
</tbody>
</table>

### 请求示例

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

## 创建 Mind

使用不同训练模式以自定义配置创建新的 AI mind。

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

**Headers:**

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

### 请求体

```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"
}
```

### 参数

<table>
<thead>
  <tr>
    <th>
      参数
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      Mind 名称(2-100 字符)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      Mind 的专业领域(例如 "Marketing"、"Engineering")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mode
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      训练模式:<code>
        keywords
      </code>
      
      、<code>
        clone
      </code>
      
      、<code>
        link
      </code>
      
       或 <code>
        manual
      </code>
      
      。默认:<code>
        keywords
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Mind 类型:<code>
        creative
      </code>
      
      、<code>
        expert
      </code>
      
       或 <code>
        user
      </code>
      
      。默认:<code>
        creative
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Mind 的用途描述
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      条件必填
    </td>
    
    <td>
      关键词数组(当 <code>
        mode
      </code>
      
       为 <code>
        keywords
      </code>
      
       时必填)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        personaContext
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      条件必填
    </td>
    
    <td>
      要模仿的人物名称/上下文(当 <code>
        mode
      </code>
      
       为 <code>
        clone
      </code>
      
       时必填;也用于自动派生关键词)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contextLink
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      条件必填
    </td>
    
    <td>
      Profile/内容 URL(当 <code>
        mode
      </code>
      
       为 <code>
        link
      </code>
      
       时必填;服务器抓取该 URL 以派生关键词)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      否
    </td>
    
    <td>
      分类标签数组(最多 20 个)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        profileImageUrl
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      外部头像图片 URL(将被下载并存储)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      为 <code>
        true
      </code>
      
       时,在后台触发 AI 头像生成
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cloneVoice
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      为 <code>
        true
      </code>
      
       时,通过 YouTube 搜索触发语音克隆(实验性)
    </td>
  </tr>
</tbody>
</table>

### Mode 取值

`mode` 参数决定你的 mind 如何训练:

- **keywords**(默认)- 使用逗号分隔的关键词训练 mind。AI 将基于这些关键词从不同来源收集相关信息,以构建 mind 的知识库。
  - **必填字段:** `keywords` - 关键词/主题数组
  - **最适合:** 特定主题或领域的通用专业能力
- **clone** - 通过提供某人的名称和上下文来克隆其风格与知识。AI 将研究并构建模仿其专业能力和沟通风格的完整 profile。
  - **必填字段:** `personaContext` - 名称及简要上下文(例如 "Ada Lovelace, pioneering computer scientist")
  - **最适合:** 模仿特定个人、历史人物或知名专家
- **link** - 使用特定 URL 的内容训练 mind。提供 profile、作品集或网站链接,AI 将分析并提取相关信息。
  - **必填字段:** `contextLink` - 内容源 URL
  - **最适合:** 基于特定网站、作品集或在线 profile 进行训练
- **manual** - 创建不进行自动训练的 mind。你将手动配置所有设置,并稍后通过 knowledge API 添加知识。
  - **无额外必填字段**
  - **最适合:** 希望完全控制训练数据的自定义配置

> **自动处理:** 当你使用 `keywords`、`clone` 或 `link` 时,后端行为与产品内 Add Mind 表单一致 —— 派生 entity 关键词(`clone`/`link` 使用 AI 辅助)并异步训练该 mind。可通过创建响应中的 `training` 区块以及下文 **Mind 训练生命周期** 中描述的专用端点来跟踪训练进度。`manual` 模式跳过该自动化,以便你稍后通过 Knowledge API 进行训练。

### Type 取值

- **creative** - 面向艺术家、设计师、作家等创意工作者
- **expert** - 面向专家、顾问及领域专家
- **user** - 面向用户 persona、客户与目标受众原型

### 响应

```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
  }
}
```

`training` 区块报告 mind 在创建时的生命周期。`keywords`、`clone` 和 `link` 模式以 `queued` 开始并在后台训练;`manual` mind 返回时即为 `completed`,且 `readyToChat` 已为 `true`。mind 的 `id` 在此调用返回时即存在,但只有当 `readyToChat` 为 `true` 时该 mind 才能作答。轮询方式见下文 **Mind 训练生命周期**。

### 示例:使用 Keywords 模式创建 Mind

```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"]
  }'
```

### 示例:使用 Clone 模式创建 Mind

```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"]
  }'
```

### 示例:使用 Link 模式创建 Mind

```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"]
  }'
```

### 示例:使用 Manual 模式创建 Mind

```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 训练生命周期

创建 mind 是异步的。`POST /v1/minds` 会立即返回一个 `id`,但对于 `keywords`、`clone` 和 `link` 模式,mind 仍在后台训练。**mind 的 id 存在并不意味着该 mind 已就绪** —— 只有当 `readyToChat` 为 `true` 时该 mind 才能作答。唯一的例外是 `manual` 模式:这类 mind 跳过数据收集,在创建的那一刻即为 `completed`。

轮询专用的训练端点,直到 mind 就绪:

```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
}
```

### 状态值

<table>
<thead>
  <tr>
    <th>
      状态
    </th>
    
    <th>
      含义
    </th>
    
    <th>
      <code>
        readyToChat
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        queued
      </code>
    </td>
    
    <td>
      训练已入队但尚未开始。
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        running
      </code>
    </td>
    
    <td>
      mind 正在主动收集知识并构建其 persona。
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        completed
      </code>
    </td>
    
    <td>
      训练完成。mind 已就绪可作答。
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        failed
      </code>
    </td>
    
    <td>
      训练未完成。请检查 <code>
        error
      </code>
      
      ,若可重试则重新训练。
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

`GET /v1/minds/{id}` 也会随 mind 的其余信息一起返回 `readyToChat`(和 `trainingStatus`),因此一次读取即可同时告诉你该 mind 是谁以及它是否已能作答。

### 训练失败时

当 `status` 为 `failed` 时,响应会包含一个带有 `code` 和 `retryable` 标志的 `error` 对象:

<table>
<thead>
  <tr>
    <th>
      错误代码
    </th>
    
    <th>
      含义
    </th>
    
    <th>
      <code>
        retryable
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        COLLECTION_FAILED
      </code>
    </td>
    
    <td>
      知识收集未能完成。
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROFILE_GEN_FAILED
      </code>
    </td>
    
    <td>
      无法生成 persona 档案。
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMEOUT
      </code>
    </td>
    
    <td>
      训练超出时间预算并被停止。
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INTERNAL
      </code>
    </td>
    
    <td>
      发生了意外的内部错误。
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

### 重新训练

如果某个 mind 以 `failed` 结束(或你只是想重建一个 `completed` 的 mind),可重新训练它:

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

这会将该 mind 重新入队,并返回一个 `status` 为 `queued` 的全新 `training` 区块。重新训练仅对已完成的 mind 有效:仍处于 `queued` 或 `running` 的 mind 会返回 `409 Conflict`,因为已有一次训练正在进行。重新训练后,请再次轮询 `GET /v1/minds/{id}/training`,直到 `readyToChat` 为 `true`。

## 头像图片

当你提供 `profileImageUrl` 时:

1. 图片从外部 URL 下载
2. 上传到安全存储
3. 响应中返回存储后的 URL

支持的格式:JPG、PNG、GIF、WEBP

## 训练原理

系统根据你选择的 mode、type 和 discipline 自动生成智能 system prompt:

- **Keywords 模式**:围绕你指定的关键词构建专业能力
- **Clone 模式**:构建模仿指定人物风格与知识的 profile
- **Link 模式**:从所提供的 URL 提取知识
- **Manual 模式**:创建一个基础助手,你将使用自定义知识进行训练

你可以在创建后 [上传知识](/api/knowledge) 进一步增强 mind。

## 计划限制

请查看生成的[套餐限制表](/api/overview)了解当前公共默认值。合同覆盖值可能不同；集成应使用认证 `PLAN_LIMIT` 响应中的 `data.limit` 和 `data.current`。Individual 套餐在 API payload 中表示为 `"premium"`。

达到上限时,你将收到 `403 Forbidden` 错误:

```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
  }
}
```

## 错误响应

### 400 Bad Request

参数缺失或无效。

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

### 401 Unauthorized

API key 无效或缺失。

### 403 Forbidden

达到计划限制。

### 500 Internal Server Error

服务器端错误(罕见)。

## 更新 Mind

更新已存在 mind 的配置,包括名称、描述、system prompt 及其他设置。

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

**Headers:**

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

### 请求体

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

### 参数

<table>
<thead>
  <tr>
    <th>
      参数
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Mind 名称(2-100 字符)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Mind 的用途描述
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      类型:<code>
        creative
      </code>
      
      、<code>
        expert
      </code>
      
       或 <code>
        user
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discipline
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Mind 的专业领域
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        systemPrompt
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      定义 mind 行为与人格的自定义 system prompt
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      否
    </td>
    
    <td>
      分类标签数组(最多 20 个)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPublic
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Mind 是否公开可访问
    </td>
  </tr>
</tbody>
</table>

### System Prompt

`systemPrompt` 字段允许你自定义 mind 的行为与响应方式。适用于:

- **Persona 自定义**:定义特定的人格特征、沟通风格或专业领域
- **响应格式**:指示 mind 以特定格式回答(例如点列表、编号列表)
- **领域约束**:将响应限制在特定主题或视角
- **语言/语调**:设定响应的语言、正式程度或语调

**System prompt 示例:**

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

### 响应

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

### 示例:更新 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."
  }'
```

### 示例:更新多个字段

```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"]
  }'
```

### 错误响应

**400 Bad Request** - 无有效字段可更新或字段值无效

**401 Unauthorized** - API key 无效或缺失

**403 Forbidden** - 无权更新此 mind(必须是 owner)

**404 Not Found** - Mind 不存在

## 获取 Mind 知识模式

获取特定 mind 按框架组织的思维模式与知识。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### 响应结构

该 endpoint 返回按框架分组的模式(例如 AOX Internal、OCEAN、DISC 等),其中的方法与能力包含出现次数与证据。

```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"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### 理解响应

- **frameworks**:包含该 mind 模式的框架数组

  - **totalOccurrences**:该框架下的模式总数
  - **methods**:检测到的思维方法或路径
  
    - **occurrences**:该方法出现的次数
    - **competencies**:该方法下的具体技能或子领域
    
      - **occurrences**:该能力下的模式数量
      - **evidence**:展示该模式的引用/片段数组
      
        - **mind**:内容中的实际片段或洞察
        - **portfolioItemId**:源材料引用
        - **createdAt**:该模式被识别的时间

### 请求示例

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

### 使用场景

- **了解 mind 的专业能力**:查看你的 mind 已学到哪些方法与能力
- **质量保障**:验证模式是否正确从训练数据中提取
- **知识缺口**:识别需要更多训练数据的领域
- **框架对比**:比较一个 mind 在不同框架下的表现

### 错误响应

**401 Unauthorized** - API key 无效或缺失

**403 Forbidden** - 无权访问此 mind

**404 Not Found** - Mind 不存在

## 重新生成 System Prompt

使用 mind 的现有知识库重新生成全部 system prompt 组件。该过程使用与 UI 中 "Generate All" 按钮相同的 AI 生成逻辑。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### 工作原理

该 endpoint 分析 mind 的知识库(portfolio items、patterns、embeddings)并生成全部 prompt 组件:

对于 **user** 类型 mind:

- Core Identity & Demographics
- Needs & Motivations
- Pain Points & Challenges
- Tone & Communication Style
- Goals & Desires
- Behavioral Patterns

对于 **expert** 类型 mind:

- Core Identity & Personality
- Professional Expertise & Credentials
- Tone & Communication Style
- Professional Approach & Methods
- Domain Knowledge

对于 **creative** 类型 mind:

- Core Identity & Personality
- Creative Philosophy & Values
- Tone & Communication Style
- Creative Approach & Methods
- Domain Expertise

### 响应

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

### 请求示例

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

### 使用场景

- **添加知识之后**:重新生成 prompt 以纳入新添加的知识条目
- **Persona 调优**:基于当前知识模式更新 persona
- **重置自定义内容**:清除手动编辑内容,并基于知识库重新生成 prompt

### 错误响应

**401 Unauthorized** - API key 无效或缺失

**403 Forbidden** - 无权修改此 mind(必须是 owner)

**404 Not Found** - Mind 不存在

**500 Internal Server Error** - 生成 prompt 失败(例如知识不足)

## 删除 Mind

永久删除 mind 及所有相关数据,包括知识、portfolio 条目和文件。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

### 响应

成功时返回 `204 No Content`,响应体为空。

### 请求示例

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

### 哪些内容会被删除

删除 mind 时,以下内容会被永久删除:

- Mind 本身及其所有配置
- 所有知识与训练数据
- 所有 portfolio 条目及关联文件
- 所有聊天历史与消息
- 头像与已上传文件

**警告:** 此操作无法撤销。

### 错误响应

**400 Bad Request** - mind ID 格式无效

**401 Unauthorized** - API key 无效或缺失

**403 Forbidden** - 无权删除此 mind(必须是 owner)

**404 Not Found** - Mind 不存在

## 下一步

- [为 mind 上传知识](/api/knowledge)
- [与 mind 聊天](/api/chat)
- 了解 [错误与限制](/api/errors)