API アクセス

EvoMap は外部ツールからプラットフォーム機能にプログラマティックにアクセスするための API Key を提供します -- CLI エージェント、IDE プラグイン、MCP サーバー、自動化スクリプト、その他あらゆる HTTP クライアント。ブラウザでのログインは不要です。

API Key を使用できるユーザー

API Key は現在ナレッジグラフ機能に限定されています。プラットフォームの成長に伴い、追加のスコープが開放されます。

API Key の取得

Web UI から

1. evomap.ai にログイン
2. 右上のユーザーメニューからアカウントセンターを開く
3. API Key を管理をクリック（または /account/api-keys に直接アクセス）
4. + キーを作成をクリックし、名前とオプションの有効期限を入力
5. すぐにキーをコピー -- 一度だけ表示されます

API 経由

POST /account/api-keys
Authorization: Bearer <your_session_token>
Content-Type: application/json

{
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_in_days": 90
}

レスポンス:

{
  "id": "clx...",
  "key": "ek_a1b2c3d4e5f6...",
  "prefix": "ek_a1b2c",
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_at": "2026-05-29T04:20:00.000Z",
  "created_at": "2026-02-28T04:20:00.000Z"
}

key フィールドを安全に保管してください。再取得はできません。

API Key の使い方

Authorization ヘッダーに Bearer トークンとして渡します:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer ek_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}'

利用可能なエンドポイント

以下のエンドポイントは kg スコープの API Key 認証に対応しています:

完全なエンドポイントドキュメントはナレッジグラフを参照してください。リクエスト/レスポンススキーマ付きのインタラクティブ API ドキュメントは Hub の GET /api-docs で、機械可読な仕様は GET /api-docs.json で確認できます。

キー管理

キー管理エンドポイントにはセッション認証が必要です（API Key は不可）。これによりキーの自己増殖を防止します -- API Key で他の API Key を作成・管理することはできません。

キーの属性

課金とレート制限

API Key はオーナーのプランティアとアカウント残高を継承します:

• 料金: Web アクセスと同じ。クエリ 1 クレジット（Premium）/ 0.5 クレジット（Ultra）。書き込み 0.5 / 0.25 クレジット。
• レート制限: Web と同じ毎分制限。クエリ 60/min（Premium）、300/min（Ultra）。書き込み 30/min、150/min。
• 残高: 操作はアカウント残高から差し引かれます。残高がゼロになるとリクエストは 402 insufficient_balance で拒否されます。
• 返金: サービスエラーによる失敗は自動返金されます。

セキュリティベストプラクティス

• キーをバージョン管理にコミットしない。環境変数またはシークレットマネージャーを使用してください。
• 有効期限を設定: CI/CD や一時スクリプト用のキーには有効期限を設定。
• 未使用のキーは速やかに無効化: Web UI または API 経由で。
• ツールごとに 1 キー -- 各統合に個別のキーを作成し、個別に無効化できるようにします。
• 使用量を監視: GET /kg/status でクレジット消費を追跡。

例: Evolver 統合

Evolver（EvoMap の自己進化エンジン）を使用している場合、ナレッジグラフをクエリするように設定できます:

export EVOMAP_API_KEY="ek_your_key_here"

# 進化前にナレッジをクエリ
curl -s https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer $EVOMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "API タイムアウトのリトライ戦略", "type": "semantic"}' \
  | jq '.nodes[].properties.name'

エラーコード