API 參考

在 Ara 中建立金鑰、驗證金鑰，並試用公開 API。

以 Markdown 格式查看

公開 API 位於 https://api.ara.so/v3。ara_ API 金鑰綁定至 建立該金鑰的 Ara 工作區。

取得 API 金鑰

  1. 登入 Ara 並開啟您的工作區。
  2. 開啟 設定 → Ara CLI。
  3. 在 CI 用 API 金鑰 下，選擇 產生金鑰。
  4. 選擇最小範圍與到期時間，然後複製金鑰。

請將金鑰視同密碼保管。將其儲存於密鑰管理工具中，切勿存放於原始碼控制系統或瀏覽器程式碼中。

驗證金鑰

在您的 Shell 中設定金鑰，並呼叫 /v3/self：

$export ARA_API_KEY="ara_..."
$
$curl https://api.ara.so/v3/self \
>  -H "Authorization: Bearer $ARA_API_KEY"

回應中包含綁定至該金鑰的組織 ID：

1{
2  "principal_type": "service_user",
3  "service_user_id": "key_3f9a",
4  "service_user_name": "ci-bot",
5  "org_id": "org_8c2d1e"
6}

在後續範例中使用該值：

$export ARA_ORG_ID="org_8c2d1e"

試用 API

列出已連接的儲存庫

需要 repos:read。

$curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/repositories" \
>  -H "Authorization: Bearer $ARA_API_KEY"

啟動工作階段

需要 run。請將 acme/web 替換為已連接至工作區的儲存庫。

$curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/sessions" \
>  -H "Authorization: Bearer $ARA_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "repo": "acme/web",
>    "prompt": "Fix the flaky auth test, add a regression case, and open a PR."
>  }'

回應中包含 session_id。工作階段建立為非同步操作。

讀取工作階段

需要 sessions:read。

$export ARA_SESSION_ID="ses_91af3c"
$
$curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/sessions/$ARA_SESSION_ID" \
>  -H "Authorization: Bearer $ARA_API_KEY"

常用範圍

範圍用途
run啟動、引導、取消及排程代理工作
sessions:read讀取工作階段、訊息、標籤、洞察及附件
repos:read、repos:write讀取儲存庫及管理索引
memory:read、memory:write讀取及管理可編輯的儲存庫備註
secrets:read、secrets:write列出密鑰名稱及寫入或刪除值
plugins:read、plugins:write讀取及管理 MCP 伺服器與 Git 外掛程式
reviews:read、reviews:write讀取或觸發拉取請求審查
analytics:read讀取使用量、佇列狀態及稽核日誌

請使用可滿足需求的最小範圍。密鑰值為唯寫，無法透過 API 讀取回來。

如需確切的請求欄位、回應結構描述及所有公開端點，請開啟 完整端點參考。

錯誤

狀態碼含義
401金鑰遺失、無效或已過期
403金鑰缺少所需範圍，或工作區無法存取
429已達速率限制。請遵守 Retry-After 標頭