OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

OpenAPI仕様とTypeScriptクライアント

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

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

エンドポイント

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

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-generator、orval、kubb など、OpenAPI 3.1互換の任意のジェネレーターが動作します。

LLMでの活用

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

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

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

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

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

カバー範囲

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

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

次のステップ

  • /_openapi.json で稼働中の仕様を取得する： /_openapi.json
  • ベアラートークンフローについて 認証 を読む
  • Sparks、Panels、Chat で各エンドポイントの解説を確認する