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

# OpenAPI Spec

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

## Endpoint

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      你能得到什么
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi.json
      </code>
    </td>
    
    <td>
      OpenAPI 3.1.0 JSON 规范。将其喂入任意生成器。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi-3.0.json
      </code>
    </td>
    
    <td>
      为 RapidAPI 等导入工具生成的 OpenAPI 3.0.2 兼容视图。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/api/v1/openapi.json
      </code>
    </td>
    
    <td>
      同一份规范，与其描述的端点放在一起提供。无需 API 密钥。
    </td>
  </tr>
</tbody>
</table>

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

## 身份验证

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

```http
Authorization: Bearer minds_…_key
```

在 [设置 → API 密钥](/settings/api-keys) 中创建一个。完整流程见 [身份验证](/docs/api/authentication)。

## 生成 TypeScript 客户端

最快的方式：使用 [`openapi-typescript`](https://openapi-ts.dev/) 从实时规范生成严格类型。

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

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

```ts
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/minds', {
  params: { query: { limit: 10 } },
})
```

更想要一个运行时 SDK？任何兼容 OpenAPI 3.1 的生成器都可以 —— [`openapi-generator`](https://openapi-generator.tech/)、[`orval`](https://orval.dev/)、[`kubb`](https://www.kubb.dev/) 等。

## 与 LLM 一起使用

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

```bash
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 功能的成熟，操作元数据可能出现轻微的结构性偏移。如果你需要一个冻结的契约，请将客户端生成步骤固定到某个构建产物上。

## 下一步

- 在 [/_openapi.json](/_openapi.json) 获取实时规范
- 阅读 [身份验证](/docs/api/authentication) 了解 bearer token 流程
- 深入 [Minds](/docs/api/minds)、[Studies](/docs/api/studies) 或 [Chat](/docs/api/chat) 查看端点演练