API Quickstart - Ara Documentation

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

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

Treat the key like a password. Store it in a secret manager, never in source control or browser code.

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:

{
  "principal_type": "service_user",
  "service_user_id": "key_3f9a",
  "service_user_name": "ci-bot",
  "org_id": "org_8c2d1e"
}

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

Scope	Use it to
`run`	Start, steer, cancel, and schedule agent work
`sessions:read`	Read sessions, messages, tags, insights, and attachments
`repos:read`, `repos:write`	Read repositories and manage indexing
`memory:read`, `memory:write`	Read and manage editable repository notes
`secrets:read`, `secrets:write`	List secret names and write or delete values
`plugins:read`, `plugins:write`	Read and manage MCP servers and git plugins
`reviews:read`, `reviews:write`	Read or trigger pull request reviews
`analytics:read`	Read usage, queue status, and audit logs

Use the narrowest scopes that work. Secret values are write-only and can never be read back through the API.

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

Errors

Status	Meaning
`401`	Missing, invalid, or expired key
`403`	The key lacks the required scope, or the workspace is not accessible
`429`	Rate limited. Honor the `Retry-After` header

​Get an API key

​Verify the key

​Try the API

​List connected repositories

​Start a session

​Read the session

​Common scopes

​Errors

Get an API key

Verify the key

Try the API

List connected repositories

Start a session

Read the session

Common scopes

Errors