API Reference

The public API lives at https://api.ara.so/v3. An ara_ API key is bound to the Ara workspace where it was created.

Get an API key

1. Sign in to Ara and open your workspace.
2. Open Settings → Ara CLI.
3. Under API keys for CI, select Generate key.
4. Choose the narrowest scopes and an expiration, then copy the key.

Verify the key

Set the key in your shell and call /v3/self:

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

The response includes the organization ID bound to the key:

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

Use that value in the remaining examples:

$
export ARA_ORG_ID="org_8c2d1e"

Try the API

List connected repositories

Requires repos:read.

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

Start a session

Requires run. Replace acme/web with a repository connected to the workspace.

$
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."
>
  }'

The response includes a session_id. Session creation is asynchronous.

Read the session

Requires 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"

Common scopes

For exact request fields, response schemas, and every public endpoint, open the full endpoint reference.

Errors