> ## 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.
# Create a session
> Opens a new session from a prompt. `repo` is optional: provide one to bind the initial checkout, or omit it for a repository-neutral start. If the running Brain later discovers an exact connected repository, Ara attaches it and continues the original task under this Session ID instead of creating another user task. The session starts immediately and runs asynchronously: poll `GET /sessions/{id}` for status and `GET /sessions/{id}/events` for incremental live output.
Scope: `run`
## OpenAPI
````yaml /openapi/openapi.json post /v3/organizations/{orgId}/sessions
openapi: 3.1.0
info:
title: Ara API
version: 3.0.0
description: >-
The Ara HTTP API. Drive cloud software-engineering agents: open sessions
against your repositories, stream their work, and manage the secrets,
knowledge, skills, and automations they run with.
All requests authenticate with an `ara_` API key sent as a bearer token.
Every resource is scoped to an organization; resolve your `org_id` once with
`GET /v3/self`.
servers:
- url: https://api.ara.so
security:
- araApiKey: []
tags:
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Sessions
description: >-
A session is one run of an agent against a repository: it reproduces the
task, writes the code, verifies it, and opens a pull request or merge
request.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: Durable notes the agent consults while it works.
- name: Memory
description: >-
Editable repository notes that are projected into native memory; generated
memory remains read-only.
- name: Skills
description: Reusable instruction bundles that activate for matching agent tasks.
- name: Automations
description: Recurring or one-time triggers that open sessions on a timetable.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- name: Repositories
description: Connected repositories, their indexing state, and generated wikis.
- name: Git Connections
description: Linked source-control accounts and the repositories they expose.
- name: Consumption
description: 'Billing-aligned usage: daily consumption and billing cycles.'
- name: Metrics
description: Aggregate analytics over sessions, change requests, and usage.
- name: Audit Logs
description: An append-only record of changes made within the organization.
- name: Organizations
description: The top-level tenant. Create, read, update, and delete organizations.
- name: Members
description: People in an organization and their pending invites.
- name: Service Users
description: Machine principals that own API keys for headless access.
- name: Roles
description: Role assignments that govern what each member can do.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- name: Guardrails
description: >-
Per-repository automation limits and the violations recorded when a limit
is hit.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Blueprints
description: >-
Read-only declarative manifests of an organization's agents (identity, run
config, triggers, suite), with credentials redacted.
- name: IP Access List
description: >-
Source-network allow-list that, when enabled, restricts the organization's
API surface to a set of CIDR ranges.
- name: Groups
description: Manually-curated member groups carrying optional per-day resource limits.
paths:
/v3/organizations/{orgId}/sessions:
parameters:
- $ref: '#/components/parameters/orgId'
post:
tags:
- Sessions
summary: Create a session
description: >-
Opens a new session from a prompt. `repo` is optional: provide one to
bind the initial checkout, or omit it for a repository-neutral start. If
the running Brain later discovers an exact connected repository, Ara
attaches it and continues the original task under this Session ID
instead of creating another user task. The session starts immediately
and runs asynchronously: poll `GET /sessions/{id}` for status and `GET
/sessions/{id}/events` for incremental live output.
Scope: `run`
operationId: createSession
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSession'
example:
prompt: >-
Fix the flaky test in src/auth/session.test.ts and add a
regression case.
repo: acme/web
provider: github
tags:
- ci
- tests
responses:
'201':
description: Session created and queued.
content:
application/json:
example:
session_id: ses_91af3c
url: https://ara.so/org/acme/sessions/ses_91af3c
status: running
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: Quota exhausted for the billing account.
content:
application/json:
example:
error: quota_exhausted
message: Monthly sandbox minutes exceeded.
'503':
description: >-
Temporarily unable to create the session: model credential preflight
could not be completed, or `env` was supplied while the deployment's
secret store is unavailable (`secret_store_unavailable`).
security:
- araApiKey:
- run
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
CreateSession:
type: object
properties:
prompt:
type: string
description: What the agent should do.
repo:
type: string
description: >-
Optional initial connected repository path. Omit it for a scratch
session. GitHub uses `owner/name`; GitLab projects may include
nested groups, such as `group/subgroup/project`.
provider:
type: string
enum:
- github
- gitlab
description: >-
Source-control provider for the repo. Defaults to GitHub first, then
GitLab if no GitHub repository matches.
model:
type: string
description: >-
Concrete model id from `GET /agent-auth/models`. Omit or use `auto`
to inherit the workspace default.
reasoning_effort:
type: string
enum:
- low
- medium
- high
- xhigh
description: Optional reasoning effort override for the selected model.
tags:
type: array
items:
type: string
branch:
type: string
description: >-
Existing branch to check out and work on; commits land on this
branch. Created off the default branch if it does not exist yet.
Mutually exclusive with `pr_number` and `ref`.
pr_number:
type: integer
minimum: 1
description: >-
Continue an existing pull request: the agent checks out its head
branch and commits back onto it (no new PR). GitHub only. Mutually
exclusive with `branch` and `ref`.
ref:
type: string
description: >-
Commit SHA, tag, or branch to snapshot: the agent starts a fresh
working branch from this ref and opens a new PR. Mutually exclusive
with `branch` and `pr_number`.
env:
type: object
additionalProperties:
type: string
description: >-
Session-scoped environment variables, injected into the agent's
shell for this session only (and its follow-up turns). Names must
match `^[A-Za-z_][A-Za-z0-9_]*$` and may not use reserved inference
names; at most 64 keys, 32 KB per value, 256 KB total. Values
override personal or workspace secrets of the same name, are
write-only (never returned by any read endpoint), and are redacted
from logs and transcripts.
create_as_user_id:
type: string
description: Attribute the session to another member (service users only).
idempotency_key:
type: string
description: >-
Idempotent create: a retried POST with the same key returns the
original session instead of creating a duplicate.
long_running_enabled:
type:
- boolean
- 'null'
description: >-
Loop override for this session: after the first pass the agent keeps
re-verifying and fixing its own work, up to `rounds_max` passes,
stopping early once a verification pass finds nothing left to do.
`true` turns the loop on for this session, `false` turns it off,
omitted inherits the agent's configuration.
rounds_max:
type:
- integer
- 'null'
minimum: 1
maximum: 100000
description: >-
Most passes over the task for this session, including the first.
Only meaningful when the loop is enabled (via `long_running_enabled`
or the agent's configuration); omitted inherits the agent's value.
Verification, cancellation, or limits can stop the session sooner.
required:
- prompt
Error:
type: object
properties:
error:
type: string
message:
type: string
responses:
BadRequest:
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: prompt_required
Unauthorized:
description: Missing, invalid, or expired key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
securitySchemes:
araApiKey:
type: http
scheme: bearer
bearerFormat: ara_
description: >-
Your `ara_` API key from Settings > Ara API. Keys are capability-scoped:
run, plugins:read, secrets:read, secrets:write, sessions:read,
knowledge:read, repos:read, repos:write, reviews:read, reviews:write,
analytics:read, org:read, org:write, attachments:read,
attachments:write, plugins:write, guardrails:read, guardrails:write.
````