Concepts
The API is small on purpose. Learn these five and you have learned the product.
One run of an agent against a repository, from prompt to change request.
An encrypted credential injected into the sandbox. Write-only.
Native Codex memory that compounds per repository across sessions.
A cron or one-time trigger that opens sessions for you.
The session lifecycle
A session is the unit of work. You create one with a prompt and a repository; it runs asynchronously through the loop below and ends carrying a pull request or merge request.
Status maps to four values: running, exit (completed), error, and
suspended (cancelled or out of quota).
Sessions are asynchronous. POST /sessions returns as soon as the run is
queued. Follow progress by polling the session and its messages.
How the pieces fit
A session runs against a connected repository. It inherits the secrets scoped to you or that repository and can use that repository’s native Codex memory. An automation opens sessions on a timetable instead of on demand. Nothing else is required to be productive.
Glossary
Organization scope
Every resource lives under an organization. Resolve your org_id with
GET /v3/self and pass it in the path of every other call.
Secret scope
Secrets are either user scope (available to your sessions) or repo scope
(available to sessions on one repository). Values are stored encrypted and
can never be read back through the API, only overwritten or deleted.
Connected repository
A GitHub repository or GitLab project Ara can access for the organization.
Sessions can only run against connected repositories; an unconnected repo
returns repo_not_connected.