> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Quickstart

> Create a key in Ara, verify it, and try the public API.

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](https://ara.so/login) and open your workspace.
2. Open **Settings → Developers**.
3. Under **API keys for CI**, select **Generate key**.
4. Choose the narrowest scopes and an expiration, then copy the key.

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

## Verify the key

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
export ARA_ORG_ID="org_8c2d1e"
```

## Try the API

### List connected repositories

Requires `repos:read`.

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
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                 |

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

For exact request fields, response schemas, and every public endpoint, open the
[full endpoint reference](/api-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                         |