API

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

以 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 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.