---
title: "Knowledge API"
description: "通过文件、关键词或链接为你的 mind 添加知识。"
---

# Knowledge API

此 API 为 Minds 中的 mind 管理知识。

通过三种方式为 mind 添加知识:**文件**、**关键词** 或 **链接**。知识会被处理、embedding,并在对话中自动检索。

**注意:** 列出、添加和删除都可通过 v1 API 使用。通过关键词搜索进行知识增强也通过同一个 add endpoint 支持。

---

## 列出知识条目

获取某个 mind 的所有知识条目。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

**示例:**

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

**响应:**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "description": "Company Employee Handbook 2025",
        "link": null,
        "filePath": "portfolio/user-id/1234567890_handbook.pdf",
        "isWatched": false,
        "createdAt": "2025-12-10T12:00:00.000Z",
        "updatedAt": "2025-12-10T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

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

<tbody>
  <tr>
    <td>
      <code>
        data.items
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      知识条目对象数组
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.total
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      该 mind 的知识条目总数
    </td>
  </tr>
</tbody>
</table>

---

## 文件上传

直接向 mind 上传文档或图片。

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

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

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

<tbody>
  <tr>
    <td>
      <code>
        file
      </code>
    </td>
    
    <td>
      file
    </td>
    
    <td>
      是
    </td>
    
    <td>
      待上传文件(最大 50MB)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      是
    </td>
    
    <td>
      内容描述
    </td>
  </tr>
</tbody>
</table>

**支持的格式:**

- 文档:PDF、DOCX、DOC、TXT、MD、RTF、CSV、JSON、XML
- 图片:JPG、JPEG、PNG、GIF、WEBP

**示例:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"
```

**响应:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Company Employee Handbook 2025",
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}
```

---

## 关键词搜索

通过在 web 上搜索关键词来添加知识。搜索 Exa 和 YouTube,提取内容,并添加到 mind 的知识库。

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

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

发送带有 `keywords` 数组(而非 `link`/`file`)的 JSON body 以触发 web 搜索式知识增强。

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

<tbody>
  <tr>
    <td>
      <code>
        keywords
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      是
    </td>
    
    <td>
      搜索关键词(最多 35 个)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        regeneratePrompt
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      之后是否重新生成 system prompt(默认:true)
    </td>
  </tr>
</tbody>
</table>

**示例:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'
```

**响应:** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "sparkId": "660e8400-e29b-41d4-a716-446655440000",
    "keywords": ["solar panel efficiency", "photovoltaic trends"],
    "queued": true,
    "regeneratePrompt": true,
    "message": "Knowledge enrichment queued with 2 keyword(s)."
  }
}
```

**注意:** 这是异步的。处理在后台运行,可能需要数分钟。

---

## 链接

通过 URL 添加知识。支持网页、YouTube 视频和研究论文。

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

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

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

<tbody>
  <tr>
    <td>
      <code>
        link
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      是
    </td>
    
    <td>
      指向 web 内容的 URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      是
    </td>
    
    <td>
      内容描述
    </td>
  </tr>
</tbody>
</table>

**示例:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://example.com/article", "description": "Industry trends article"}'
```

**响应:** `201 Created`

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "link": "https://example.com/article",
    "description": "Industry trends article",
    "createdAt": "2025-12-10T12:00:00.000Z"
  }
}
```

**支持的链接类型:**

- 网页(通过抓取提取内容)
- YouTube 视频(自动提取字幕)
- 研究论文(arxiv 等)

---

## 监视(自动更新)

基于链接的知识条目可被"监视",以按周周期自动检查内容更新。检测到变化时,知识会被重新处理并重新 embedding。

监视在产品 UI 中管理。通过 API 列出知识条目时,可通过 `isWatched` 字段查看监视状态。

**注意:** 监视仅适用于基于链接的知识,不支持文件或关键词搜索。

---

## 更新知识条目

更新已存在知识条目的描述。

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

**Headers:**

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

**请求体:**

```json
{
  "description": "Updated description for this knowledge item"
}
```

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

<tbody>
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      是
    </td>
    
    <td>
      更新后的描述(不可为空)
    </td>
  </tr>
</tbody>
</table>

**示例:**

```bash
curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated handbook description"}'
```

**响应:**

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Updated handbook description",
    "link": null,
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "isWatched": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T08:30:00.000Z"
  }
}
```

### 错误响应

**400 Bad Request** - 无有效字段可更新或描述为空

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

**404 Not Found** - 知识条目或 mind 未找到

---

## 通过关键词增强(便利接口)

关键词式知识增强的便利别名。

**Endpoint:** `POST /api/v1/minds/{mindId}/knowledge/enrich`

等价于带 `keywords` body 的 `POST /api/v1/minds/{mindId}/knowledge`。详情参见 [关键词搜索](#keyword-search)。

**示例:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge/enrich" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'
```

---

## 删除知识条目

永久删除知识条目及所有关联数据(embedding、模式、文件)。

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

**Headers:**

```text
Authorization: Bearer minds_your_api_key
```

**示例:**

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

**响应:** `204 No Content`(成功时响应体为空)

### 哪些内容会被删除

- 知识条目记录
- 所有关联的向量 embedding
- 所有关联模式
- 已上传的文件(如为文件类型)

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

---

## 处理原理

1. **上传** - 内容被存储,API 返回成功
2. **提取** - 后台处理提取文本(抓取、字幕、OCR、视觉)
3. **Embedding** - 内容被转换为向量 embedding
4. **检索** - 聊天时,相关知识通过 semantic search 自动检索

---

## 错误

<table>
<thead>
  <tr>
    <th>
      状态码
    </th>
    
    <th>
      信息
    </th>
    
    <th>
      原因
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Link and description are required
      </code>
    </td>
    
    <td>
      缺少必填字段
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Keywords array is required
      </code>
    </td>
    
    <td>
      关键词为空或缺失
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        File too large
      </code>
    </td>
    
    <td>
      文件超过 50MB 上限
    </td>
  </tr>
  
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        Can only watch link-based knowledge
      </code>
    </td>
    
    <td>
      尝试监视文件
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      <code>
        Mind not found or access denied
      </code>
    </td>
    
    <td>
      Mind ID 无效或无访问权限
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      <code>
        Unsupported Content-Type
      </code>
    </td>
    
    <td>
      Content-Type header 错误
    </td>
  </tr>
</tbody>
</table>

---

## 下一步

- [与你的 mind 聊天](/docs/api/chat)
- [创建 mind](/docs/api/minds)
- [API 错误与限制](/docs/api/errors)