APIリファレンス

Araでキーを作成し、検証して、パブリックAPIを試す。

Markdownとして表示

パブリックAPIは https://api.ara.so/v3 にあります。ara_ APIキーは、作成されたAraワークスペースに紐付けられています。

APIキーを取得する

  1. Araにサインインして、ワークスペースを開きます。
  2. 設定 → Ara CLI を開きます。
  3. CI用APIキー の下にある キーを生成 を選択します。
  4. 最小限のスコープと有効期限を選択し、キーをコピーします。

キーはパスワードと同様に扱ってください。シークレットマネージャーに保存し、ソースコントロールやブラウザのコードには絶対に含めないでください。

キーを検証する

シェルにキーを設定し、/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:writeMCPサーバーとgitプラグインを読み取り、管理する
reviews:read、reviews:writeプルリクエストレビューを読み取るまたはトリガーする
analytics:read使用状況、キューのステータス、監査ログを読み取る

機能する最小限のスコープを使用してください。シークレットの値は書き込み専用であり、APIを通じて読み取ることはできません。

正確なリクエストフィールド、レスポンススキーマ、およびすべてのパブリックエンドポイントについては、 完全なエンドポイントリファレンスを参照してください。

エラー

ステータス意味
401キーが存在しない、無効、または期限切れ
403キーに必要なスコープがない、またはワークスペースにアクセスできない
429レート制限。Retry-After ヘッダーに従ってください