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:

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

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

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:

{
  "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
• OpenAPI specification
• Machine entry: https://ara.so/llms.txt