> ## 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

> Drive Ara from an outside agent with an ara_ API key and the /v3 REST API.

Outside agents and CI drive Ara through the public REST API. Public customer MCP is retired. Do not connect Cursor, Claude, or Grok Bot to `/mcp/ara`.

## 1. Create an API key

In Ara, open **Settings → Developers** (the Code / API keys picker) and generate
an `ara_` key. A new key from that picker includes the ordinary public scopes
needed for this walkthrough: `run`, `sessions:read`, `org:read`, `skills:read`,
`repos:read`, and the other non-elevated picker options.

Keep `org:write`, `guardrails:write`, and `sessions:debug` off unless an owner
or admin explicitly grants them. Never put the key in source, prompts, or logs.

## 2. Confirm the key

Call `GET /v3/self` first:

```bash theme={null}
curl https://api.ara.so/v3/self \
  -H "Authorization: Bearer $ARA_API_KEY"
```

The response includes the key's workspace (`org_id` / slug) and granted
`scopes`. Use that workspace id or slug in every later path.

## 3. Create a session

```bash theme={null}
curl -X POST "https://api.ara.so/v3/organizations/$ORG_ID/sessions" \
  -H "Authorization: Bearer $ARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fix the flaky auth test, add a regression case, and open a PR.",
    "repo": "acme/web",
    "provider": "github",
    "idempotency_key": "one-stable-key-per-logical-run"
  }'
```

* `prompt` is required.
* `repo` and `provider` are optional. Omit them for a repository-neutral
  scratch session.
* `idempotency_key` is a JSON body field, not an HTTP header. Reuse it when
  retrying the same logical create.
* A new create returns HTTP 201. An idempotent replay returns HTTP 200 with
  the original session. Both include `session_id`, `url`, and `status`.

## 4. Poll until the session finishes

```bash theme={null}
curl "https://api.ara.so/v3/organizations/$ORG_ID/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ARA_API_KEY"
```

Status is `running`, `exit` (completed successfully), `error`, or `suspended`
(cancelled or quota). Only `exit` is successful. When a pull or merge request
exists, the retrieved session's nullable `pr_url` is the URL. It is not part of
the create response.

## 5. Read the result

Use `url` to open the session in Ara. Use `pr_url` when the session opened a
change request. Send a follow-up with
`POST /v3/organizations/{orgId}/sessions/{sessionId}/messages`.

## Errors

A valid key that lacks a route's allowlist scope receives HTTP 403:

```json theme={null}
{
  "error": {
    "type": "missing_scope",
    "message": "This endpoint requires the org:read scope",
    "required_scope": "org:read"
  }
}
```

`endpoint_not_available` means the route is not a public API-key surface. Do
not retry it with the same key.

## What not to do

* Do not call `https://api.ara.so/mcp/ara`. That public transport returns 410.
* Do not treat run-scoped `/mcp/ara` (a live sandbox principal) as something
  an outside coding agent should configure.
* Do not send a WorkOS/JWT session token to `/v3`. The public API accepts
  `ara_` keys only.

## Next

* [Endpoint reference](/api-reference)
* [OpenAPI specification](/openapi.json)
* Machine entry: [https://ara.so/llms.txt](https://ara.so/llms.txt)