Skip to main content
Breaking changes to the published contract are gated in CI by an oasdiff check, so anything listed here as removed or changed shipped deliberately.

​
August 15, 2026 — Tightened CORS preflight header advertisement

  • Cross-origin preflight responses now advertise only the request headers a browser client sends (authorization, content-type, mcp-session-id, x-ara-org-slug, x-ara-trace-id, accept). Operator and inbound-webhook signing headers, which are only used on server-to-server routes that never preflight, are no longer disclosed.

​
August 15, 2026 — Secret access auditing and write-only immutability

  • Secret access is now tracked in audit logs: decrypting secrets for a session run or brokered connector invocation emits a canonical secret.accessed audit event with the exact secret names and target run/connector scope.
  • Workspace secrets support an immutable revealable flag (defaulting to false for new secrets). Write-only secrets (revealable: false) cannot be escalated back to revealable once stored, and their plaintext values are never disclosed on reveal endpoints.
  • Relay egress observation mode is active for org-MCP and vendor broker relays, recording destination origin/host and allowlist verification telemetry on every outbound request without disrupting active integrations.

​
August 12, 2026 — Per-organization memory for new cloud machines

  • A cloud sandbox’s writable filesystem is RAM-backed at roughly half its memory, so a box’s memory is also its disk ceiling. BLAXEL_SANDBOX_ORG_MEMORY_MB now accepts orgId:mb pairs and sizes newly provisioned machines for those organizations, for repositories whose dependency tree does not fit the default.
  • An explicit memory request is now clamped at the real 32 GB per-machine cap rather than the 16 GB large-repository tier. A request above the old ceiling was silently halved, so a machine asked for at 32 GB came up at 16 GB.
  • This applies only when a machine is CREATED. A persistent box is reused by name and keeps the size it was born with, so an existing machine takes the new size at its next reset.

​
August 12, 2026 — Retry a session on a different model over REST

  • POST /v3/organizations/{org}/sessions/{id}/messages now accepts optional model and reasoning_effort, so a stalled or failed session can be retried on a different model through the REST API. Previously only the MCP tools could do this: REST accepted the fields and silently ignored them, returning 200 with the session still on its original model.
  • A model override always starts a new continuation run, because a run’s model is fixed at its first execution. Omitting both fields preserves today’s behavior exactly.
  • Both surfaces now validate through one resolver, so an id accepted on one is accepted on the other. An unusable override is refused with 400 (invalid_model / invalid_reasoning_effort) instead of being dropped.
  • An override is refused with 409 model_override_requires_finished_session while the session is still queued or running, because switching models requires a new continuation run and a live run would have kept its original model. Send the message without an override to steer a live session.
  • An overridden model is credential-checked before the message is stored, so a model whose provider credential is disconnected returns the actionable agent_model_key_missing instead of a run that dies when a worker picks it up.

​
August 11, 2026: Sessions cannot give an MCP server a command to run

  • A running session can no longer create or update an organization MCP server that uses stdio transport, or that supplies a command. It gets mcp_server_command_requires_human. Add those in workspace settings instead.
  • Everything else is unchanged. A session can still connect, update and disconnect http and sse servers, supply write-only secrets for them, toggle them on and off, and use every tool a configured server exposes. The one-click plugin flow is unaffected.
  • External principals are unaffected: your API keys, the ara CLI, the Ara MCP server you connect from your machine, and workspace settings can all still add a stdio server.
  • Why: a stdio server’s command is executed by Ara inside your later sessions, and a new server applies to your workspace by default. Repo content and issue text can influence an agent, so choosing what gets executed belongs to a person.

​
August 11, 2026: Sessions ask for secrets instead of storing them

  • A running session can no longer store or delete a secret. ara_secret_set and ara_secret_delete are now available only to external principals: your own API keys, the ara CLI, and the Ara MCP server you connect from your machine. A session that tries gets secret_write_requires_human.
  • Sessions can still LIST secret names, and still use every secret the workspace has. Only storing a value changed.
  • When an agent needs a credential it does not have, it calls request_secret, which shows an “Add secret” card in the session with the exact variable name and why it is needed. You supply the value and it reaches the agent’s next turn. Nothing about that flow changed; it is now the only route.
  • Why: a stored secret applies to every later session in the workspace, so a session that can store one can change what all your future sessions trust. Repo content and issue text can influence an agent, so that decision belongs to a person. Existing secrets, and writes from the dashboard or your API keys, are unaffected.

​
August 11, 2026: Reserved secret names, and mid-session secret delivery

  • Secret writes now refuse names that control how a later process loads code or resolves the program it runs, because a stored secret is re-applied to every later session in the workspace. POST /v3/organizations/{org}/secrets returns invalid_secret_name for BASH_ENV, ENV, PATH, NODE_OPTIONS, PYTHONPATH, RUBYOPT, JAVA_TOOL_OPTIONS, git’s own hooks such as GIT_SSH_COMMAND and GIT_PAGER, and anything starting with LD_, DYLD_, GIT_CONFIG, or BASH_FUNC_. Set these from your repository’s own scripts instead, where they apply only to the commands you intend.
  • A value already stored under one of those names is no longer applied to new sessions. Delete it and, if you still need it, set it from your repository setup instead. Deleting such a name continues to work.
  • Names that point a tool at a different server are unaffected, so private registries and proxies keep working: NPM_CONFIG_REGISTRY, PIP_INDEX_URL, HTTPS_PROXY, and custom CA bundles are all still accepted.
  • Adding, changing, or deleting a workspace secret now reliably reaches sessions that are already running, so an agent’s next command sees it without waiting for a new session. Sessions using a persistent workspace previously kept the value they started with until their next session.

​
August 10, 2026: Organization secrets and optional usage notes

  • Secret list, set, and delete operations accept scope: organization for workspace-wide secrets. These secrets are available to runs throughout the workspace rather than being stored per repository.
  • Secret writes accept an optional note. Use it to tell Ara or teammates how to use a secret, and include a repository name when the value is intended for one codebase. Lists return the note but never return the secret value.
  • The former repo scope remains a compatibility alias. Its repository fields are accepted but ignored, and the stored secret is organization-wide. Add useful repository context to note. Personal user secrets are unchanged.
  • GET /v3/organizations/{org}/setup-helper has been removed. Its deprecated empty compatibility payload no longer exists; start a repository-optional session and describe the device or codebase instead.
  • The old repository Environment blueprint, image-build, required-plugin, authored setup-script, and readiness storage has also been removed. Connected repository access, workspace secrets, native .ara/runbook.md, and plugin connections remain independent capabilities that an agent can use during a task; none is a session-start prerequisite.
  • The internal environment_not_ready run status has been retired. Historical rows are normalized to infra_error; new sessions are never blocked on repository setup, keys, plugins, or readiness metadata.

​
August 9, 2026: Session-scoped environment variables on create

  • POST /v3/organizations/{org}/sessions accepts an optional env object of environment variables for that session only. They are injected into the agent’s shell alongside your repository and account secrets, override both on a name collision, and follow the session across follow-up messages (continuation turns see the same environment). Nothing is written to your organization’s secret stores.
  • Names must be valid shell environment names (^[A-Za-z_][A-Za-z0-9_]*$) and may not use reserved inference names such as OPENAI_API_KEY or ANTHROPIC_API_KEY; violations return 400 invalid_env. At most 64 variables, 32 KB per value, 256 KB total.
  • Values are write-only: encrypted at rest, never returned by any read endpoint, and redacted from logs and transcripts, matching the secrets API’s write-only philosophy.

​
August 8, 2026: Guardrails gain merge-policy fields

  • The Guardrails object on GET/PUT /v3/organizations/{org}/repositories/{owner}/{repo}/guardrails gains three optional fields: auto_merge_protected_paths (newline-separated globs whose matches require a standing human approval before an unattended merge), auto_merge_max_changed_lines (0 disables the size limit), and auto_merge_delete_branch (post-merge source-branch cleanup; forks and branches other open pull requests target are never deleted). Additive and optional, so existing clients are unaffected.

​
August 8, 2026 — Point a session at a branch, a pull request, or a ref

  • POST /v3/organizations/{org}/sessions accepts three new, mutually-exclusive start targets. Set at most one; setting more than one returns 400 conflicting_target, and absence keeps the previous behavior (a fresh ara/agent/* branch off the default that opens a new pull request).
    • branch: check out an existing branch and commit onto it (created off the default branch if it does not exist yet).
    • pr_number: continue an existing GitHub pull request. The agent checks out its head branch and commits land back on the pull request, with no new one opened. The pull request is validated at create time: an unknown number is 404 pr_not_found, a closed or merged one is 409 pr_not_open, and a pull request whose head is on a fork is 422 pr_head_is_fork (the app cannot push there). GitLab is not yet supported for this field.
    • ref: snapshot a commit SHA, tag, or branch. The agent starts a fresh working branch from that ref and opens a new pull request. The ref is resolved to an immutable commit at create time, so an unknown ref is 404 ref_not_found, and abbreviated SHAs and moving branches/tags are pinned to the revision you requested rather than whatever the tip is when the run starts.
  • A malformed or blank branch / ref returns 400 invalid_branch / 400 invalid_ref. A branch pointing at a protected branch (the default, main, or master) returns 422 branch_protected, because the agent cannot push there.

​
August 8, 2026: Loop-configured session creates fail fast while Loop is unavailable

  • POST /v3/organizations/{org}/sessions with long_running_enabled: true now returns 400 invalid_request at admission while Loop mode is unavailable on the current runtime. Previously the session was accepted and queued, then failed at execution with harness1_pi_long_running_not_supported.
  • The request fields themselves are unchanged; nothing changes for sessions that do not set long_running_enabled.

​
August 8, 2026 — Repo-scoped secret writes from an agent run require owner or admin

  • An agent run writing a repository-scoped secret through Ara’s own MCP surface now requires the run’s user to be an owner or admin of the workspace, matching the rule already enforced on /v3 and in the web app. A repo secret is pushed into every running session for that repository, so it is workspace configuration rather than a per-run setting.
  • Listing secret names is unchanged, and a run can still manage the caller’s own user-scoped secrets.

​
August 7, 2026 — Attachments always download, and their content type comes from the file itself

  • POST /v3/organizations/{org}/attachments no longer stores the Content-Type your multipart part declares. The stored type is derived from the file’s own bytes: a real PNG, JPEG, GIF, WebP, WebM, or MP4 keeps its media type, and everything else is stored as application/octet-stream. The content_type field returned by the upload and list endpoints reports that stored type, so it always matches what a download actually returns.
  • Downloads are now served with Content-Disposition: attachment, so a browser saves the file instead of rendering it. An HTML or SVG file uploaded as an attachment can no longer execute as a page on the storage host.
  • Files uploaded before this change that were stored under a markup or script content type (text/html, image/svg+xml, application/javascript, …) are no longer downloadable: GET /v3/organizations/{org}/attachments/{id} answers 404, and those entries come back from the list endpoint with url: null. Re-upload the file to get a working download URL. Documents, archives, text, and media uploaded earlier are unaffected.

​
August 7, 2026 — Repository secret writes require owner or admin

  • POST and DELETE on /v3/organizations/{org}/secrets with scope: "repo" now require the caller to be an owner or admin of the workspace, answering 403 otherwise. User-scoped secrets are unchanged: any member manages their own. A repo-secret write is pushed into every running session for that repository, so it is workspace configuration rather than a personal setting.
  • The same rule already applied to repository-secret operations in the web app; this brings the public API in line with it. An integration that performs these writes needs a key minted by an owner or admin.

​
August 7, 2026 — Failed-authentication throttling

  • Repeated requests that present an invalid or expired credential from the same client are now throttled. After a burst of failed authentications the API answers 429 with a Retry-After header; back off for that long before retrying. This bounds API-key guessing and token enumeration. Successful requests and requests with no credential are unaffected, so ordinary authenticated traffic is never throttled.

​
August 6, 2026: Credentials are no longer read from the URL query string

  • The API no longer accepts a bearer credential passed as an ?access_token= query parameter. Requests authenticate with the Authorization: Bearer header only; a token sent via the query string is ignored and the request answers 401 with {"error": "missing_bearer"}.
  • URLs are routinely recorded in browser history, proxy logs, and Referer headers, so a credential placed there can leak outside the request (CWE-598). Header-only authentication closes that path.
  • No published client or SDK ever sent tokens in the query string, so no integration changes are expected. The MCP OAuth compatibility endpoint, whose discovery flow requires a query credential, is unchanged.

​
August 6, 2026 — Rate limiting on authentication endpoints

  • The email-code sign-in and verification endpoints now enforce a per-client, per-account rate limit. When the limit is hit they answer 429 with a Retry-After header (seconds to wait); back off for that long before retrying. This guards accounts against code-guessing and send-spam and does not affect ordinary authenticated /v3 traffic.

​
August 1, 2026 — Provider connection routes retired

  • The agent-auth provider-connection endpoints remain in the published contract but now answer 410 with {"error": "provider_connections_temporarily_unavailable"}. Provider credentials can no longer be submitted, stored, or used through the API. The affected routes are:
  • GET /v3/organizations/{orgId}/agent-auth/models stays live and is now the way to discover which models a workspace can run. Ara serves a curated model catalog rather than per-workspace provider credentials.
  • GET /v3/organizations/{orgId}/agent-auth/status stays live.

​
July 19, 2026 — System automations hidden by default

  • /v3 automation listings omit Ara’s own system automations by default, so a client sees the automations its workspace authored rather than internal plumbing.

​
July 15, 2026 — Automations resource and scopes

  • Added an automation-centric resource with triggers as sub-resources:
  • Added the automations:read and automations:write API-key scopes that govern them.

​
July 15, 2026 — Repository memory and notes

  • Added workspace memory and knowledge notes to the public API:
See the API quickstart to get a key, and the full endpoint reference for the current contract.