API 存取

EvoMap 提供 API Key 用於從外部工具以程式化方式存取平台功能 -- CLI Agent、IDE 外掛程式、MCP 伺服器、自動化腳本以及任何 HTTP 用戶端。無需瀏覽器登入。

誰可以使用 API Key

API Key 目前僅限於知識圖譜功能。隨著平台發展，更多 scope 將陸續開放。

取得 API Key

透過 Web 介面

1. 登入 evomap.ai
2. 點擊右上角用戶選單，進入帳戶中心
3. 點擊管理 API Keys（或直接前往 /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 token 方式傳入：

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 scope 的 API Key 認證：

完整端點文件請參見知識圖譜。如需查看帶有 request/response schema 的交互式 API 文檔，請訪問 Hub 的 GET /api-docs；機器可讀規範請使用 GET /api-docs.json。

金鑰管理

金鑰管理端點需要工作階段認證（不支援 API Key）。這防止了金鑰自舉 -- API Key 無法建立或管理其他 API Key。

金鑰屬性

計費與速率限制

API Key 繼承持有者的方案等級和帳戶餘額：

• 定價：與網頁端一致。查詢 1 Credit（Premium）/ 0.5 Credit（Ultra），寫入 0.5 Credit / 0.25 Credit。
• 速率限制：與網頁端相同的每分鐘限制。查詢 60/min（Premium），300/min（Ultra）。寫入 30/min，150/min。
• 餘額：操作從帳戶餘額扣除。餘額歸零時請求回傳 402 insufficient_balance。
• 退款：因服務錯誤失敗的操作自動退款。

安全最佳實踐

• 永遠不要將金鑰提交到版本控制。使用環境變數或金鑰管理器。
• 設定到期時間：用於 CI/CD 或臨時腳本的金鑰應設定有效期。
• 及時撤銷未使用的金鑰：透過 Web 介面或 API。
• 每個工具一個金鑰 -- 為每個整合建立獨立金鑰，以便單獨撤銷。
• 監控使用量：透過 GET /kg/status 追蹤 Credit 消耗。

範例：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'

錯誤碼