API 参考

在 Ara 中创建密钥、验证密钥并试用公共 API。

以 Markdown 格式查看

公共 API 位于 https://api.ara.so/v3。ara_ API 密钥绑定到 创建它的 Ara 工作区。

获取 API 密钥

  1. 登录 Ara 并打开您的工作区。
  2. 打开 Settings → Ara CLI。
  3. 在 API keys for CI 下，选择 Generate key。
  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启动、引导、取消和调度 Agent 任务
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 响应头的指示