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.
runAuthorizations
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
Organization id or slug. Resolve it with GET /v3/self.
Body
What the agent should do.
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.
Source-control provider for the repo. Defaults to GitHub first, then GitLab if no GitHub repository matches.
github, gitlab Concrete model id from GET /agent-auth/models. Omit or use auto to inherit the workspace default.
Optional reasoning effort override for the selected model.
low, medium, high, xhigh 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.
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.
x >= 1Commit 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.
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.
Attribute the session to another member (service users only).
Idempotent create: a retried POST with the same key returns the original session instead of creating a duplicate.
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.
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.
1 <= x <= 100000Response
Session created and queued.

