API

Changes to the public /v3 REST API and its scopes.

View as Markdown

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 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 — Repo secrets and secret-executing blueprints 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.
  • PUT /v3/organizations/{org}/environment/recipe now requires owner or admin when the blueprint carries a session_start or preview section. Those sections execute at session start with the repository’s decrypted secrets in the environment, so authoring one is a secret-disclosure decision. Blueprints that only use build-time sections (base, env, initialize, knowledge, clone) are unchanged and remain open to every member.
  • Both rules already applied to the same 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:

    POST /v3/organizations/{orgId}/agent-auth/azure-openai/connect
    GET  /v3/organizations/{orgId}/agent-auth/byok/usage
    POST /v3/organizations/{orgId}/agent-auth/byok/{provider}/connect
    DEL  /v3/organizations/{orgId}/agent-auth/byok/{provider}
    DEL  /v3/organizations/{orgId}/agent-auth/{provider}

  • 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:

    /v3/organizations/{orgId}/automations
    /v3/organizations/{orgId}/automations/{automationId}
    /v3/organizations/{orgId}/automations/{automationId}/triggers
    /v3/organizations/{orgId}/automations/{automationId}/triggers/{triggerId}

  • 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:

    /v3/organizations/{orgId}/memory/notes
    /v3/organizations/{orgId}/memory/notes/{memoryId}
    /v3/organizations/{orgId}/knowledge/notes
    /v3/organizations/{orgId}/knowledge/notes/{noteId}

See the API quickstart to get a key, and the full endpoint reference for the current contract.