OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

OpenAPI 规范与 TypeScript 客户端

Minds API 的机器可读 OpenAPI 3.1.0 规范。生成带类型的 TypeScript 客户端，或将 JSON 直接喂给你的 LLM。

Minds 公共 API 提供机器可读的 OpenAPI 3.1.0 规范。构建带类型的客户端，或把 JSON 交给 LLM —— 与本文档同一份真相来源。

Endpoint

URL你能得到什么
https://getminds.ai/_openapi.jsonOpenAPI 3.1.0 JSON 规范。将其喂入任意生成器。
https://getminds.ai/api/v1/openapi.json同一份规范，与其描述的端点放在一起提供。无需 API 密钥。

该规范仅包含声明了 OpenAPI 元数据的公共 /api/v1/** 端点。内部端点（admin、debug、cron、MCP 等）会被排除。

身份验证

规范中的每个操作都由 ApiKeyAuth 保护 —— 将你的个人 API 密钥作为 bearer token 发送：

Authorization: Bearer minds_…_key

在 设置 → API 密钥 中创建一个。完整流程见 身份验证。

生成 TypeScript 客户端

最快的方式：使用 openapi-typescript 从实时规范生成严格类型。

npx openapi-typescript https://getminds.ai/_openapi.json -o minds.d.ts

然后配合 openapi-fetch 使用，得到一个完全带类型的客户端：

import createClient from 'openapi-fetch'
import type { paths } from './minds'

const client = createClient<paths>({
  baseUrl: 'https://api.getminds.ai',
  headers: { Authorization: `Bearer ${process.env.MINDS_API_KEY}` },
})

// All params + responses are typed from the live spec.
const { data, error } = await client.GET('/api/v1/sparks', {
  params: { query: { limit: 10 } },
})

更想要一个运行时 SDK？任何兼容 OpenAPI 3.1 的生成器都可以 —— openapi-generator、orval、kubb 等。

与 LLM 一起使用

JSON 规范足够小，可以直接粘进对话：

curl -s https://getminds.ai/_openapi.json | pbcopy

然后粘贴到 ChatGPT / Claude / Cursor，并配上类似这样的提示：

这是 Minds API 的 OpenAPI 规范。给我写一个 Python 脚本，列出我的 sparks 并打印它们的名称。

该规范包含请求/响应模式、示例负载以及 bearer token 身份验证约定 —— 模型需要的一切都在其中。

覆盖范围

该规范列出每一个 /api/v1/** 端点。当路由带有 defineRouteMeta 块时，会附带完整的请求/响应模式；没有该块的路由只显示路径 + 方法和一段通用描述。我们会随着时间逐步覆盖整个接口面 —— 无论如何规范都保持准确，因为它由实时路由器生成，而非手工维护。

关于稳定性的说明： OpenAPI 生成依赖 Nitro 的实验性 openAPI 标志。规范格式是稳定的（OpenAPI 3.1.0）；随着底层 Nitro 功能的成熟，操作元数据可能出现轻微的结构性偏移。如果你需要一个冻结的契约，请将客户端生成步骤固定到某个构建产物上。

下一步