---
title: "OpenAPI仕様とTypeScriptクライアント"
description: "Minds APIの機械読み取り可能なOpenAPI 3.1.0仕様。型定義されたTypeScriptクライアントを生成するか、JSONをそのままLLMに流し込めます。"
---

# OpenAPI仕様

MindsのパブリックAPIは、機械読み取り可能なOpenAPI 3.1.0仕様を提供しています。型定義されたクライアントをビルドすることも、JSONをそのままLLMに渡すことも可能です。このドキュメントと完全に同一の信頼できる情報源（Source of Truth）となります。

## エンドポイント

<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キーを送信してください。

```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-generator`](https://openapi-generator.tech/)、[`orval`](https://orval.dev/)、[`kubb`](https://www.kubb.dev/) など、OpenAPI 3.1互換の任意のジェネレーターが動作します。

## LLMでの活用

JSON仕様は十分に軽量なため、チャットに直接ドロップできます。

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

その後、ChatGPT、Claude、Cursorなどに以下のようなプロンプトと一緒に貼り付けます。

> 以下はMinds APIのOpenAPI仕様です。私のMindを一覧表示し、その名前を出力するPythonスクリプトを書いてください。

この仕様には、リクエスト/レスポンスのスキーマ、ペイロードの例、ベアラートークン認証のコントラクトが含まれているため、モデルが必要とするすべての情報が揃っています。

## カバー範囲

この仕様には、`defineRouteMeta({ openAPI: … })` を介してオプトインされた `/api/v1/**` エンドポイントのみがリストされています。対象範囲は順次拡大中ですが、仕様は手動で管理されるのではなく、稼働中のルーターから自動生成されるため、常に正確に保たれます。

> **安定性に関する注意：** OpenAPIの生成は、Nitroの実験的な `openAPI` フラグ上で動作しています。仕様フォーマット自体は安定（OpenAPI 3.1.0）していますが、基盤となるNitro機能の成熟に伴い、オペレーションメタデータの構造に軽微な変更が生じる可能性があります。固定されたコントラクトが必要な場合は、クライアント生成ステップをビルドアーティファクトに固定（Pin）してください。

## 次のステップ

- `/_openapi.json` で稼働中の仕様を取得する： [/_openapi.json](/_openapi.json)
- ベアラートークンフローについて [認証](/docs/api/authentication) を読む
- [Minds](/docs/api/minds)、[Studies](/docs/api/studies)、[Chat](/docs/api/chat) で各エンドポイントの解説を確認する