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 中生成和管理 API key。

在 Authorization header 中包含你的 API key:

Authorization: Bearer minds_your_api_key_here

OpenAPI 规范

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

Content Type

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

Content-Type: application/json

对于文件上传,使用:

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 并与之聊天的快速示例:

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

下一步

• 了解 身份验证
• 探索 Minds endpoint
• 阅读 知识管理
• 理解 Chat 补全
• 创建 Studies 进行多 mind 调研
• 查看 延迟与性能
• 通过 MCP 集成 连接
• 查看 错误与限制

计划限制

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

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

查看计划

需要帮助?

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

• 查看我们的 指南
• 通过反馈表单联系我们
• 加入社区讨论

n8n 工作流

使用 Minds n8n 社区节点 来创建 Study、预览研究计划、检索 Study 和已保存的摘要，或将操作公开给 AI Agent。在自托管 n8n 上安装 n8n-nodes-minds 并连接 Minds API 密钥。该包已发布在 npm 上；n8n 验证正在审核中，因此尚无法在 n8n Cloud 上使用。请在 Minds 中单独审核并开始研究。

面向智能体的 Stripe 账单

新订阅和回答额度充值使用现有 Stripe 价格。提出购买建议前先读取已认证的目录；购买资格、账户归属、试用、税费和折扣遵循 Minds 应用相同的账单服务。请取得买方同意，并在创建订阅时取得明确的条款及撤回权声明确认。

使用由 1–128 个字母、数字、下划线或连字符组成的固定 Idempotency-Key 发起结账。超时后复用同一个键和请求内容；同一键下更改购买内容会被拒绝。响应包含 data.url 和 data.checkoutSessionId。原样向买方返回 URL。结账 URL 不代表付款成功；现有订阅的修改仍在 Minds 账单设置中进行。

{
  "kind": "subscription",
  "priceId": "price_from_catalog",
  "planType": "premium",
  "billingCountry": "DE",
  "legalAcceptance": { "termsAccepted": true, "withdrawalConsent": true }
}

MPP 和 x402 用于当前账户所有、状态开放、收款方式为 send_invoice 的 USD 或 EUR 账单，且待付金额至少为 50 个货币最小单位。自动收款继续使用 Stripe 托管账单页面。付款挑战提供包含税费和折扣的实际待付金额。MPP 要求所属 Stripe 账户拥有企业资料。x402 还要求加密支付资格和已配置的支付协调服务，仅通过 Base USDC 支付 USD 账单，并要求 mppx 路由绑定扩展；缺少该扩展的钱包客户端无法支付此路由。

保留 Authorization: Bearer 作为 Minds 身份，MPP 凭证放在 Payment-Authorization，x402 凭证放在 PAYMENT-SIGNATURE。原生 MPP 客户端也可仅在此路由使用 Authorization: Payment，并在 Minds-Authorization 中提供 Minds bearer。不要将支付凭证放入模型可见的 MCP 参数。结果不确定时使用原始凭证重试；新凭证不得触发第二次扣款。Stripe 确认和签名 Webhook 决定服务交付。

在 /openapi.json 中发现支付选项；402 响应给出动态金额。/.well-known/acp.json 公布 /api/acp 下的托管结账适配器，版本为 2026-04-17。创建会话时在 line_items 中填写一个 Stripe 价格、对应的 currency 和 capabilities: {}；billingCountry、团队席位 quantity 和订阅 legalAcceptance 放入 metadata。读取、更新、完成和取消使用 /checkout_sessions/{id} 以及 /complete 或 /cancel。POST 需要幂等键。更新和完成接受空请求体：需要买方操作时返回 continue_url，仅在 Stripe 确认后报告完成。

UCP 发现文档位于 /.well-known/ucp，版本为 2026-08-25；REST 结账位于 /api/ucp，与 MCP 和账单 API 使用相同的 Stripe 会话。发布兼容的平台配置，并使用在同一 HTTPS 来源托管元数据文档的 Minds OAuth 客户端；个人 API 密钥不能声明任意平台配置。每次请求发送 UCP-Agent: profile="https://your-platform.example/.well-known/ucp"，写入请求同时发送 Idempotency-Key。支付处理器列表为空，因为买方在 Stripe Checkout 完成付款。

就绪 Webhook 订阅

使用访问源资源的同一已认证 API 密钥或 OAuth 连接。GET /api/v1/events 返回允许的事件及准确的输入和载荷架构。POST /api/v1/events/subscribe 创建或续订确定性订阅；POST /api/v1/events/unsubscribe 按原事件、参数和回调网址停止订阅，不会取消研究。受众筛选需 operationId；研究筛选需 studyId 和 runId。对应 MCP 方法为 events/list、events/subscribe 和 events/unsubscribe，通过协议 2026-07-28 的 server/discover 发现。

{
  "name": "study.run.finished",
  "arguments": {
    "studyId": "163bcb31-6ca7-4fef-91bd-9b963a9dd39f",
    "runId": "663bcb31-6ca7-4fef-91bd-9b963a9dd39f"
  },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example/mcp-events",
    "secret": "whsec_<base64-encoded-signing-key>"
  },
  "cursor": null
}

HTTPS 回调必须回显签名验证请求中的 challenge。请求使用 Standard Webhooks 标头 webhook-id、webhook-timestamp、webhook-signature 和 X-MCP-Subscription-Id。whsec_ 密钥解码后须为 24–64 字节。拒绝私有地址、重定向和含凭据的网址。验证失败返回 MCP -32015 及原因，不激活订阅。HTTP 2xx 表示已收到；暂时失败按有限次数指数退避重试并保留事件 ID，410 和 413 停止交付。后续操作前应按事件 ID 去重。

响应含 id、refreshBefore、cursor:null 和 truncated:false。ttlMs 可请求更短期限；省略或 null 授予有限默认期限，上限 86400000 毫秒。相同凭据主体、回调、事件和参数续订同一 ID。密钥轮换时短暂用新旧两把密钥签名。到期或撤销访问后停止交付。载荷不含 Bearer 凭据或研究回答。