Skip to main content
POST
Create a session

Authorizations

Authorization
string
header
required

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.

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

Body

application/json
prompt
string
required

What the agent should do.

repo
string

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
enum<string>

Source-control provider for the repo. Defaults to GitHub first, then GitLab if no GitHub repository matches.

Available options:
github,
gitlab
model
string

Concrete model id from GET /agent-auth/models. Omit or use auto to inherit the workspace default.

reasoning_effort
enum<string>

Optional reasoning effort override for the selected model.

Available options:
low,
medium,
high,
xhigh
tags
string[]
branch
string

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
integer

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.

Required range: x >= 1
ref
string

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
object

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
string

Attribute the session to another member (service users only).

idempotency_key
string

Idempotent create: a retried POST with the same key returns the original session instead of creating a duplicate.

long_running_enabled
boolean | null

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
integer | null

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 range: 1 <= x <= 100000

Response

Session created and queued.