---
title: "API 概览"
description: "Minds API 介绍 —— 以编程方式访问 mind 和管理知识。"
---

# API 概览

欢迎使用 Minds API 文档。我们的 API 允许你以编程方式创建与管理 AI mind、上传知识,并与它们交互。

## 快速开始

Minds API 遵循 REST 原则设计。我们的 API 拥有可预测的面向资源的 URL、接受 JSON 编码的请求体、返回 JSON 编码的响应,并使用标准的 HTTP 响应码、身份验证和动词。

### Base URL

**生产环境:** `https://getminds.ai/api/v1` 或 `https://api.getminds.ai/v1`

**本地开发:** `http://localhost:3000/api/v1`

两个生产环境 base URL 完全等价。推荐使用 `api.getminds.ai` 子域名以获得更简洁的集成 URL。

### 身份验证

所有 API endpoint 都需要通过 API key 进行身份验证。你可以在 [Settings → API Keys](/settings/api-keys) 中生成和管理 API key。

在 `Authorization` header 中包含你的 API key:

```bash
Authorization: Bearer minds_your_api_key_here
```

### OpenAPI 规范

机器可读的 OpenAPI 3.1.0 规范发布在 [`/_openapi.json`](/_openapi.json)。使用该规范生成带类型的客户端（TypeScript、Python 等），或将其投入 LLM 以一次性生成集成代码。示例见 [OpenAPI](/docs/api/openapi)。

### Content Type

所有发送数据的请求应包含 `Content-Type` header:

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

对于文件上传,使用:

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

## 可用 Endpoint

### Minds

使用自定义配置创建和管理 AI mind(agent)。

- `GET /api/v1/minds` - 列出所有 Mind
- `GET /api/v1/minds/{mindId}` - 获取 Mind 详情
- `POST /api/v1/minds` - 创建新的 Mind
- `PUT /api/v1/minds/{mindId}` - 更新 Mind
- `DELETE /api/v1/minds/{mindId}` - 删除 Mind
- `POST /api/v1/minds/{mindId}/regenerate-prompt` - 基于知识重新生成 system prompt

### Knowledge

管理你的 mind 的知识。

- `GET /api/v1/minds/{mindId}/knowledge` - 列出知识条目
- `POST /api/v1/minds/{mindId}/knowledge` - 添加知识(链接、文件或关键词搜索)
- `PUT /api/v1/minds/{mindId}/knowledge/{itemId}` - 更新知识条目
- `DELETE /api/v1/minds/{mindId}/knowledge/{itemId}` - 删除知识条目
- `POST /api/v1/minds/{mindId}/knowledge/enrich` - 通过关键词搜索丰富知识(便利别名)
- `GET /api/v1/minds/{mindId}/knowledge/patterns` - 按框架获取知识模式

### Chat

通过 chat 补全与你的 mind 交互。

- `POST /api/v1/minds/{mindId}/completion` - 发送消息并获取响应

### Studies

创建和管理用于调研多个 mind 的 AI 面板。

- `GET /api/v1/studies` - 列出所有面板
- `POST /api/v1/studies` - 创建新面板
- `GET /api/v1/studies/{studyId}` - 获取面板详情及消息历史
- `POST /api/v1/studies/{studyId}/ask` - 向所有面板 mind 提问(SSE 流)
- `POST /api/v1/studies/{studyId}/export` - 将面板结果导出为报告
- `GET /api/v1/studies/{studyId}/export-status` - 查询导出作业状态
- `GET /api/v1/studies/{studyId}/export-download` - 下载导出的 PDF

### User

用户相关 endpoint。

- `GET /api/v1/auth/me` - 获取当前已认证用户
- `GET /api/v1/user/shareable-sparks` - 列出可分享的 mind

### API Keys

管理你的身份验证 API key。

- `GET /api/v1/api-keys` - 列出你的 API key
- `POST /api/v1/api-keys` - 创建新的 API key
- `DELETE /api/v1/api-keys/{keyId}` - 删除 API key

## 快速示例

下面是一个创建 mind 并与之聊天的快速示例:

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

## 下一步

- 了解 [身份验证](/docs/api/authentication)
- 探索 [Minds endpoint](/docs/api/minds)
- 阅读 [知识管理](/docs/api/knowledge)
- 理解 [Chat 补全](/docs/api/chat)
- 创建 [Studies](/docs/api/studies) 进行多 mind 调研
- 查看 [延迟与性能](/docs/api/latency)
- 通过 [MCP 集成](/mcp/overview) 连接
- 查看 [错误与限制](/docs/api/errors)

## 计划限制

受支持的付费套餐包含 API 和 MCP 访问。集成应处理结构化的 `plan_limited` 和 `429` 响应，而不是硬编码限制。Individual 套餐在 API payload 中表示为 `"premium"`。

以下公共默认值由产品使用的同一套餐限制和功能访问契约生成。产品中显示的账户专属或 Enterprise 合同覆盖值优先。

:plan-limits-table[查看计划](/settings?tab=subscription)

## 需要帮助?

如果你对 API 有疑问或需要支持:

- 查看我们的 [指南](/guide)
- 通过反馈表单联系我们
- 加入社区讨论