{ "openapi": "3.1.0", "info": { "title": "Ara API", "version": "3.0.0", "description": "The Ara HTTP API. Drive cloud software-engineering agents: open sessions against your repositories, stream their work, and manage the secrets, knowledge, skills, and automations they run with.\n\nAll requests authenticate with an `ara_` API key sent as a bearer token. Every resource is scoped to an organization; resolve your `org_id` once with `GET /v3/self`." }, "servers": [ { "url": "https://api.ara.so" } ], "security": [ { "araApiKey": [] } ], "tags": [ { "name": "Account", "description": "Verify a key and resolve the organization it belongs to." }, { "name": "Sessions", "description": "A session is one run of an agent against a repository: it reproduces the task, writes the code, verifies it, and opens a pull request or merge request." }, { "name": "Secrets", "description": "Encrypted credentials injected into the agent's sandbox. Write-only: values can be set but never read back." }, { "name": "Knowledge", "description": "Durable notes the agent consults while it works." }, { "name": "Memory", "description": "Editable repository notes that are projected into native memory; generated memory remains read-only." }, { "name": "Skills", "description": "Reusable instruction bundles Ara selects semantically from their descriptions for matching agent tasks." }, { "name": "Automations", "description": "Recurring or one-time triggers that open sessions on a timetable." }, { "name": "Change Request Reviews", "description": "Automated senior-engineer reviews posted on pull requests and merge requests." }, { "name": "Repositories", "description": "Connected repositories, their indexing state, and generated wikis." }, { "name": "Git Connections", "description": "Linked source-control accounts and the repositories they expose." }, { "name": "Consumption", "description": "Billing-aligned usage: daily consumption and billing cycles." }, { "name": "Metrics", "description": "Aggregate analytics over sessions, change requests, and usage." }, { "name": "Audit Logs", "description": "An append-only record of changes made within the organization." }, { "name": "Organizations", "description": "The top-level tenant. Create, read, update, and delete organizations." }, { "name": "Members", "description": "People in an organization and their pending invites." }, { "name": "Service Users", "description": "Machine principals that own API keys for headless access." }, { "name": "Roles", "description": "Role assignments that govern what each member can do." }, { "name": "Attachments", "description": "Files uploaded to the organization and shared with sessions, downloaded via short-lived signed URLs." }, { "name": "Guardrails", "description": "Per-repository automation limits and the violations recorded when a limit is hit." }, { "name": "MCP Servers", "description": "Org-level Model Context Protocol servers exposed to the agent. Secret values are write-only." }, { "name": "Settings", "description": "Organization configuration: namespaced settings and the run tag policy." }, { "name": "Blueprints", "description": "Read-only declarative manifests of an organization's agents (identity, run config, triggers, suite), with credentials redacted." }, { "name": "IP Access List", "description": "Source-network allow-list that, when enabled, restricts the organization's API surface to a set of CIDR ranges." }, { "name": "Groups", "description": "Manually-curated member groups carrying optional per-day resource limits." } ], "components": { "securitySchemes": { "araApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ara_", "description": "Your `ara_` API key from Settings > Ara API. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, automations:read, automations:write, agent_auth:read. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:debug is privileged: it expands diagnostic session events only for organization owners/admins." } }, "parameters": { "orgId": { "name": "orgId", "in": "path", "required": true, "description": "Organization id or slug. Resolve it with `GET /v3/self`.", "schema": { "type": "string" } } }, "responses": { "Ok": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } }, "BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "prompt_required" } } } }, "Conflict": { "description": "The request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "last_owner" } } } }, "Unauthorized": { "description": "Missing, invalid, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unauthorized" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "session_not_found" } } } }, "Forbidden": { "description": "The key lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "forbidden" } } } } }, "schemas": { "AgentAuthStatus": { "type": "object", "properties": { "ara": { "type": "boolean" }, "ara_subscription_available": { "type": "boolean" }, "ara_openai_available": { "type": "boolean" } }, "required": [ "ara", "ara_subscription_available", "ara_openai_available" ], "additionalProperties": false }, "AgentModel": { "type": "object", "properties": { "id": { "type": "string", "description": "Concrete reviewed model id accepted by session creation." }, "label": { "type": "string" }, "detail": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "label", "provider" ] }, "AgentModelList": { "type": "object", "properties": { "providers": { "type": "object", "properties": { "codex": { "type": "boolean" }, "copilot": { "type": "boolean" }, "openrouter": { "type": "boolean" }, "araOpenai": { "type": "boolean" }, "araGateway": { "type": "boolean" }, "byok": { "type": "object", "additionalProperties": { "type": "boolean" } }, "ara": { "type": "boolean" } }, "required": [ "codex", "copilot", "openrouter", "araOpenai", "araGateway", "byok" ] }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AgentModel" } } }, "required": [ "providers", "models" ] }, "Attachment": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "url": { "type": "string", "description": "A signed download URL for the file." }, "created_at": { "type": "string", "format": "date-time" } } }, "AuditLogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "description": "The action performed, e.g. `secret.created`." }, "actor": { "description": "Who performed the action.", "type": [ "string", "null" ] }, "target": { "description": "The affected resource.", "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Automation": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "instructions": { "description": "The system instructions the automation runs with.", "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean", "description": "A paused (`false`) automation's triggers never fire." }, "tools": { "type": "object", "properties": { "mcp_servers": { "description": "`null` inherits every enabled org MCP server.", "type": [ "array", "null" ], "items": { "type": "string" } }, "app_tools": { "type": "array", "items": { "type": "string" } } } }, "environment": { "type": "object", "properties": { "repo": { "description": "Provider-native repository path. GitHub uses `owner/name`; GitLab may include nested groups.", "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "github", "gitlab" ] } } }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/Trigger" }, "description": "Every condition that fires this automation. Empty until you add one." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "An automation: its instructions, tools, environment binding, and triggers." }, "BulkRepoRequest": { "type": "object", "properties": { "repositories": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "Repository in `owner/name` form." }, { "type": "object", "properties": { "owner": { "type": "string" }, "repo": { "type": "string" } }, "required": [ "owner", "repo" ] } ] } } }, "required": [ "repositories" ], "description": "A list of repositories to operate on. Each entry is either an `owner/name` string or an `{ owner, repo }` object." }, "BulkRepoResult": { "type": "object", "properties": { "repo": { "type": "string", "description": "Provider-native repository path. GitHub uses `owner/name`; GitLab may include nested groups." }, "status": { "type": "string", "description": "Per-repository status, e.g. `indexing`, `removed`, or `error`." }, "error": { "type": "string", "description": "Present only when `status` is `error`." }, "repo_enabled": { "type": "boolean", "description": "True when the repository row exists even though provisioning failed." }, "retryable": { "type": "boolean" }, "action": { "type": "string", "enum": [ "reconnect_gitlab", "grant_gitlab_project_permission" ] } }, "description": "The outcome of a bulk operation for a single repository." }, "ClaimCliPairingRequest": { "type": "object", "properties": { "pairing_code": { "type": "string" } }, "required": [ "pairing_code" ], "additionalProperties": false }, "CliPairingFailureRequest": { "type": "object", "properties": { "pairing_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "failure_code": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "pairing_id", "failure_code" ], "additionalProperties": false }, "CompleteOnboardingImportRequest": { "anyOf": [ { "type": "object", "properties": { "handoff": { "type": "string" }, "imported_secret_count": { "type": "integer", "minimum": 0, "maximum": 500 } }, "required": [ "handoff", "imported_secret_count" ], "additionalProperties": false }, { "type": "object", "properties": { "pairing_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "imported_secret_count": { "type": "integer", "minimum": 0, "maximum": 500 } }, "required": [ "pairing_id", "imported_secret_count" ], "additionalProperties": false } ] }, "ConsumptionDay": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "group": { "description": "Present when the request groups by a dimension.", "type": [ "string", "null" ] }, "sandbox_minutes": { "type": "number" }, "tokens": { "type": "integer" }, "cost_usd": { "type": "number" } } }, "CreateAutomation": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name. Defaults to the first line of `instructions`." }, "instructions": { "type": "string", "description": "The system instructions the automation runs with." }, "repo": { "type": "string", "description": "Connected repository path. GitHub uses `owner/name`; GitLab projects may include nested groups, such as `group/subgroup/project`." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "Source-control provider for the connected repository. Defaults to GitHub first, then GitLab if no GitHub repository matches." }, "model": { "description": "Model override. `null` uses the workspace default. New runs accept only the currently available Ara model catalog.", "type": [ "string", "null" ] }, "tools": { "type": "object", "properties": { "mcp_servers": { "description": "Org MCP server slugs this automation may use. `null` inherits every enabled org server.", "type": [ "array", "null" ], "items": { "type": "string" } }, "app_tools": { "type": "array", "items": { "type": "string" }, "description": "Catalog connector slugs (e.g. `linear`, `sentry`)." } } } }, "required": [ "instructions", "repo" ], "description": "Creates the automation's configuration. It has no triggers until you add one via `POST /automations/{automationId}/triggers`, so it will not fire on its own yet." }, "CreateMemoryNote": { "type": "object", "properties": { "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "title": { "type": "string", "description": "Optional title. It is trimmed, defaults to 'Memory note' when omitted or blank, and must be at most 160 characters." }, "content": { "type": "string", "description": "Non-empty explicit memory content. It is trimmed before storage and limited to 240 KiB UTF-8." } }, "required": [ "repo", "content" ] }, "CreateNote": { "type": "object", "properties": { "name": { "type": "string" }, "trigger": { "type": "string" }, "body": { "type": "string" }, "scope": { "type": "string" }, "repo_filter": { "type": "string" } }, "required": [ "name", "body" ] }, "CreateOrganization": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string", "description": "Optional URL slug; generated from the name when omitted." } }, "required": [ "name" ] }, "CreateOrganizationSecretsBulk": { "type": "object", "properties": { "variables": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Uppercase identifier, e.g. `NPM_TOKEN`." }, "value": { "type": "string", "description": "Secret value. Stored encrypted and never returned." }, "note": { "type": "string", "maxLength": 2000, "description": "Optional source or usage description. Never include a secret value." } } }, "description": "Workspace secrets to create or replace atomically." } }, "required": [ "variables" ] }, "CreatePrReview": { "type": "object", "properties": { "repository": { "type": "string", "description": "Repository or project path." }, "pr_number": { "type": "integer", "description": "The pull request number or merge request IID to review." }, "pr_url": { "type": "string", "description": "GitHub pull request URL or GitLab merge request URL. Alternative to `repository` + `pr_number`." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "Source-control provider. Defaults to GitHub first, then GitLab if no GitHub review trigger exists." }, "instructions": { "type": "string", "description": "Optional guidance to focus the review." } } }, "CreateSecret": { "type": "object", "properties": { "name": { "type": "string", "description": "Uppercase identifier, e.g. `NPM_TOKEN`." }, "value": { "type": "string", "description": "The secret value. Stored encrypted and never returned." }, "note": { "type": "string", "maxLength": 2000, "description": "Optional usage guidance for agents and workspace members. Include the repository name when the secret is intended for one codebase." }, "scope": { "type": "string", "enum": [ "organization", "user", "repo" ], "default": "user" }, "repo": { "type": "string", "description": "Deprecated context field for the `repo` compatibility scope. The value is stored workspace-wide." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "Deprecated provider context for the `repo` compatibility scope." } }, "required": [ "name", "value" ] }, "CreateSession": { "type": "object", "properties": { "prompt": { "type": "string", "description": "What the agent should do. Maximum 256 KiB when UTF-8 encoded." }, "repo": { "type": "string", "description": "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`." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "Source-control provider for the repo. Defaults to GitHub first, then GitLab if no GitHub repository matches." }, "model": { "type": "string", "description": "Concrete model id from `GET /agent-auth/models`. Omit or use `auto` to inherit the workspace default." }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh" ], "description": "Optional reasoning effort override for the selected model." }, "hands_mode": { "type": "string", "enum": [ "adaptive", "brain_only" ], "description": "Physical execution policy. `adaptive` (default) starts with Brain and lazily acquires Hands when work needs a shell, files, browser, or sandbox. `brain_only` permanently forbids physical Hands and secret materialization for this Session and all of its continuation Attempts; independently created Sessions keep their own policy." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "At most 50 tags; each tag is at most 100 UTF-8 bytes." }, "branch": { "type": "string", "description": "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`." }, "pr_number": { "type": "integer", "minimum": 1, "description": "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`." }, "ref": { "type": "string", "description": "Commit 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`." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "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." }, "idempotency_key": { "type": "string", "description": "Idempotent create: a retried POST with the same key returns the original session instead of creating a duplicate." }, "long_running_enabled": { "type": [ "boolean", "null" ], "description": "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." }, "rounds_max": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "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." } }, "required": [ "prompt" ] }, "CreateSkill": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "Describe what the skill does and when an agent should use it. Ara uses this description for semantic selection." }, "instructions": { "type": "string" }, "activation_keywords": { "type": "array", "items": { "type": "string" }, "description": "Optional search aliases retained for compatibility. They improve explicit search but do not activate the skill automatically." }, "is_enabled": { "type": "boolean" } }, "required": [ "name", "instructions" ] }, "CreateTrigger": { "type": "object", "properties": { "frequency": { "type": "string", "description": "Cron expression, e.g. `0 3 * * *`, for a recurring trigger." }, "every_seconds": { "type": "integer", "description": "Fixed interval in seconds. Alternative to `frequency`." }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Run-at time for a one-time trigger. Alternative to `frequency`." }, "enabled": { "type": "boolean", "default": true } }, "description": "Adds a schedule trigger to the automation. Provide exactly one of `frequency`, `every_seconds`, or `scheduled_at`." }, "Deployment": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string", "const": "github-native-engineer-api" }, "environment": { "type": "string" }, "is_pr_environment": { "type": "boolean" }, "branch": { "type": [ "string", "null" ] }, "commit_sha": { "type": [ "string", "null" ] }, "deployment_id": { "type": [ "string", "null" ] }, "public_url": { "type": [ "string", "null" ] }, "checked_at": { "type": "string" } }, "required": [ "ok", "service", "environment", "is_pr_environment", "branch", "commit_sha", "deployment_id", "public_url", "checked_at" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "GitConnection": { "type": "object", "properties": { "id": { "description": "Provider connection id. GitHub uses the installation id; GitLab uses the Ara connection id.", "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "git_connection_id": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "The source-control provider." }, "host": { "type": "string", "description": "The source-control host, e.g. `github.com` or `gitlab.com`." }, "account_login": { "type": "string", "description": "The linked account's login." }, "account_type": { "type": [ "string", "null" ], "enum": [ "user", "organization", null ] }, "connected_at": { "type": "string", "format": "date-time" } } }, "GitConnectionRepository": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Provider-native repository path. GitLab projects may include nested groups." }, "full_path": { "type": "string", "description": "Provider-native repository path. GitLab projects may include nested groups." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "The source-control provider." }, "host": { "type": "string", "description": "The source-control host, e.g. `github.com` or `gitlab.com`." }, "web_url": { "type": "string", "format": "uri" }, "private": { "type": "boolean" }, "default_branch": { "type": [ "string", "null" ] }, "connected": { "type": "boolean", "description": "Whether this repository is already connected to the organization." } } }, "GitPlugin": { "type": "object", "properties": { "id": { "description": "Provider connection id. GitHub uses the installation id; GitLab uses the Ara connection id.", "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "git_plugin_id": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "The source-control provider." }, "host": { "type": "string", "description": "The source-control host, e.g. `github.com` or `gitlab.com`." }, "account_login": { "type": "string", "description": "The linked account's login." }, "account_type": { "type": [ "string", "null" ], "enum": [ "user", "organization", null ] }, "connected_at": { "type": "string", "format": "date-time" } } }, "GitPluginRepository": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Provider-native repository path. GitLab projects may include nested groups." }, "full_path": { "type": "string", "description": "Provider-native repository path. GitLab projects may include nested groups." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "The source-control provider." }, "host": { "type": "string", "description": "The source-control host, e.g. `github.com` or `gitlab.com`." }, "web_url": { "type": "string", "format": "uri" }, "private": { "type": "boolean" }, "default_branch": { "type": [ "string", "null" ] }, "connected": { "type": "boolean", "description": "Whether this repository is already connected to the organization." } } }, "Guardrails": { "type": "object", "properties": { "auto_fix_new_issues": { "type": "boolean" }, "auto_audit_on_connect": { "type": "boolean" }, "pr_risk_assessment": { "type": "boolean" }, "auto_merge_prs": { "type": "boolean" }, "auto_merge_max_risk": { "type": "string", "enum": [ "zero", "low", "medium", "high" ] }, "auto_merge_require_no_blocking_findings": { "type": "boolean" }, "auto_merge_require_ara_authored": { "type": "boolean" }, "auto_merge_require_ci_green": { "type": "boolean" }, "auto_merge_require_ara_verify": { "type": "boolean" }, "auto_merge_require_migration_approval": { "type": "boolean" }, "auto_merge_review_context": { "type": "string", "enum": [ "all_review_bots", "ara_review_bot_only" ] }, "auto_merge_custom_prompt": { "type": "string" }, "auto_merge_protected_paths": { "type": "string", "description": "Newline-separated glob patterns; changes touching a matching path require a standing human approval before an unattended merge. Lines starting with # are comments." }, "auto_merge_max_changed_lines": { "type": "integer", "minimum": 0, "description": "Maximum total changed lines (additions plus deletions) an unattended merge may carry. 0 disables the limit." }, "auto_merge_delete_branch": { "type": "boolean", "description": "Delete the source branch after an unattended merge. Fork branches and branches other open pull requests target are never deleted." } }, "description": "Per-repository automation guardrails. On update, every property is optional and only the supplied fields change." }, "IndexedRepository": { "type": "object", "properties": { "repo_id": { "type": "string" }, "full_name": { "type": "string", "description": "Provider-native repository path. GitHub uses `owner/name`; GitLab may include nested groups." }, "indexing_status": { "type": "string", "enum": [ "pending", "indexing", "indexed", "failed" ] }, "has_wiki": { "type": "boolean" }, "last_indexed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "IndexingStatus": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Provider-native repository path. GitHub uses `owner/name`; GitLab may include nested groups." }, "status": { "type": "string", "enum": [ "not_indexed", "pending", "indexing", "indexed", "failed" ] }, "progress": { "description": "Fraction complete from 0 to 1.", "type": [ "number", "null" ] }, "last_indexed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Invite": { "type": "object", "properties": { "invite_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "KnowledgeFolder": { "type": "object", "properties": { "folder_id": { "type": "string" }, "name": { "type": "string" }, "note_count": { "type": "integer" } } }, "McpServer": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "source": { "type": "string" }, "transport": { "type": "string", "enum": [ "http", "stdio", "sse" ] }, "url": { "type": [ "string", "null" ] }, "command": { "type": [ "string", "null" ] }, "args": { "type": "array", "items": { "type": "string" } }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "auth_type": { "type": "string", "enum": [ "none", "oauth", "bearer" ] }, "secret_names": { "type": "array", "items": { "type": "string" }, "description": "The names of the secrets configured for this server. Secret values are write-only and are never returned." }, "access": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "An org-level MCP server. Secret values are write-only and are never returned; only `secret_names` lists which secrets are set." }, "McpServerInput": { "type": "object", "properties": { "name": { "type": "string" }, "transport": { "type": "string", "enum": [ "http", "stdio", "sse" ] }, "icon": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "auth_type": { "type": "string", "enum": [ "none", "oauth", "bearer" ] }, "secrets": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Write-only. Secret values to store for this server. Never returned in any response." }, "enabled": { "type": "boolean" } }, "required": [ "name", "transport" ], "description": "Request body for creating or updating an MCP server. On update, every property is optional and only the supplied fields change." }, "Member": { "type": "object", "properties": { "user_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "format": "email", "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "joined_at": { "format": "date-time", "type": [ "string", "null" ] } } }, "MemoryNote": { "type": "object", "properties": { "memory_id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "An explicit editable note for one connected repository." }, "MemoryNoteList": { "type": "object", "properties": { "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryNote" } }, "total": { "type": "integer" } } }, "MemoryNoteResponse": { "type": "object", "properties": { "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "item": { "$ref": "#/components/schemas/MemoryNote" } } }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "seq": { "type": "integer", "description": "Monotonic sequence number; use as `after_seq` to poll forward." }, "role": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Note": { "type": "object", "properties": { "note_id": { "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string", "description": "When the agent should consult this note." }, "body": { "type": "string" }, "scope": { "type": [ "string", "null" ] }, "repo_filter": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OnboardingImportDecision": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "pending" } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "approved" }, "selected_names": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "selected_names" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "completed" }, "selected_names": { "type": "array", "items": { "type": "string" } }, "imported_secret_count": { "type": "integer", "minimum": 0 } }, "required": [ "status", "selected_names", "imported_secret_count" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "expired" } }, "required": [ "status" ], "additionalProperties": false } ] }, "OnboardingImportDecisionRequest": { "anyOf": [ { "type": "object", "properties": { "handoff": { "type": "string" } }, "required": [ "handoff" ], "additionalProperties": false }, { "type": "object", "properties": { "pairing_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "pairing_id" ], "additionalProperties": false } ] }, "OnboardingImportHandoff": { "type": "object", "properties": { "handoff": { "type": "string" } }, "required": [ "handoff" ], "additionalProperties": false }, "OnboardingImportSummary": { "type": "object", "properties": { "env_file_count": { "type": "integer", "minimum": 0, "maximum": 10000 }, "project_count": { "type": "integer", "minimum": 0, "maximum": 10000 }, "detected_secrets": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "pattern": "^[A-Z][A-Z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "name", "description" ], "additionalProperties": false } }, "imported_secret_count": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "env_file_count", "project_count" ], "additionalProperties": false }, "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "membership_role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ], "description": "The caller's membership role in this organization. This is not an app-wide product role." }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ], "deprecated": true, "description": "Deprecated alias for `membership_role`." }, "plan": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "PrReview": { "type": "object", "properties": { "pr_review_id": { "type": "string" }, "repo": { "description": "Repository or project path.", "type": [ "string", "null" ] }, "repository": { "type": "string", "description": "Repository or project path." }, "pr_number": { "type": "integer" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "Source-control provider for the reviewed change request." }, "kind": { "type": "string", "enum": [ "pull_request", "merge_request" ], "description": "Provider-native change request kind." }, "pr_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "summary": { "description": "Short summary of the review's findings.", "type": [ "string", "null" ] }, "comment_count": { "description": "Number of inline comments posted.", "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "format": "date-time", "type": [ "string", "null" ] } } }, "Repository": { "type": "object", "properties": { "repo_id": { "type": "string" }, "owner": { "type": "string" }, "name": { "type": "string" }, "full_name": { "type": "string", "description": "Provider-native repository path. GitHub uses `owner/name`; GitLab may include nested groups." }, "repo_full_name": { "type": "string", "description": "Connected repository name, preserving the legacy field name." }, "provider": { "type": "string", "enum": [ "github", "gitlab" ], "description": "Source-control provider for this connected repository." }, "full_path": { "type": "string", "description": "Provider-native repository path. For GitLab this may include nested groups." }, "web_url": { "description": "Provider web URL for the repository.", "type": [ "string", "null" ] }, "private": { "type": "boolean" }, "default_branch": { "type": [ "string", "null" ] }, "connected": { "type": "boolean", "description": "Whether agents can run against this repository." }, "wiki_indexed": { "type": "boolean", "description": "Whether wiki/code indexing is enabled for this repository." } } }, "RepositoryProvisionFailure": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "repo_enabled": { "type": "boolean", "description": "True when the repository row was committed before provisioning failed." }, "retryable": { "type": "boolean" }, "action": { "type": "string", "enum": [ "reconnect_gitlab", "grant_gitlab_project_permission" ] } }, "required": [ "error", "message", "repo_enabled", "retryable" ], "description": "A partial GitLab repository enablement that did not finish agent or webhook provisioning." }, "RoleAssignment": { "type": "object", "properties": { "user_id": { "type": "string" }, "app_role": { "type": "string", "enum": [ "pro", "regular" ], "description": "App-wide Ara product role. This is not an organization membership role." }, "role": { "type": "string", "enum": [ "pro", "regular" ], "deprecated": true, "description": "Deprecated alias for `app_role`." }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] } } }, "Self": { "type": "object", "properties": { "principal_type": { "type": "string", "enum": [ "service_user", "user" ], "description": "API keys resolve to `service_user`; MCP OAuth grants resolve to `user`." }, "service_user_id": { "type": "string", "description": "Present when `principal_type` is `service_user`." }, "service_user_name": { "description": "Present when `principal_type` is `service_user`.", "type": [ "string", "null" ] }, "org_id": { "type": "string", "description": "Organization pinned to the current credential." }, "user_id": { "type": "string", "description": "Present when `principal_type` is `user`." }, "user_name": { "description": "Present when `principal_type` is `user`.", "type": [ "string", "null" ] }, "email": { "description": "Present when `principal_type` is `user`.", "type": [ "string", "null" ] }, "organization_name": { "description": "Display name of the organization pinned to this credential.", "type": [ "string", "null" ] }, "organization_slug": { "description": "URL slug of the organization pinned to this credential.", "type": [ "string", "null" ] }, "mcp_connections": { "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] } }, "required": [ "client_id", "client_name", "last_used_at" ] }, "description": "Active MCP OAuth client grants for the signed-in user and organization." } } }, "SendSessionMessageResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "delivery": { "type": "string" }, "continuation_session_id": { "description": "The stable logical Session id after an accepted follow-up. Continue polling this id; Ara may run the turn in a hidden execution Attempt.", "type": [ "string", "null" ] } }, "required": [ "ok" ] }, "Session": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "exit", "error", "suspended" ], "description": "running, exit (completed), error, or suspended (cancelled/quota)." }, "url": { "type": "string", "description": "Web URL to watch the session." }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "title": { "type": [ "string", "null" ] }, "prompt": { "description": "The opening instruction, truncated to 16 KiB. Check prompt_truncated; read the session messages for the full text.", "type": [ "string", "null" ] }, "prompt_truncated": { "type": "boolean", "description": "True when prompt was cut to the 16 KiB echo limit." }, "prompt_bytes": { "description": "UTF-8 byte length of the full prompt, before truncation.", "type": [ "integer", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "repo": { "type": [ "string", "null" ] }, "provider": { "description": "Source-control provider for the session repository.", "type": [ "string", "null" ], "enum": [ "github", "gitlab" ] }, "model": { "description": "Concrete model selected for this session, or null when inherited.", "type": [ "string", "null" ] }, "reasoning_effort": { "type": [ "string", "null" ] }, "hands_mode": { "type": "string", "enum": [ "adaptive", "brain_only" ], "description": "Durable physical execution policy. Brain-only sessions never acquire a shell, browser, sandbox, or physical secret environment." }, "branch": { "type": [ "string", "null" ] }, "pr_url": { "type": [ "string", "null" ] }, "pr_title": { "type": [ "string", "null" ] }, "result_summary": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "cost_usd": { "description": "Total model spend in USD across the session's turns. Null when usage was never reported.", "type": [ "number", "null" ] }, "usage": { "type": "object", "properties": { "input_tokens": { "type": [ "integer", "null" ] }, "output_tokens": { "type": [ "integer", "null" ] }, "total_tokens": { "type": [ "integer", "null" ] } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "description": "Token usage totals for the session. Fields are null for runs that predate usage persistence." }, "context": { "type": "object", "properties": { "tokens": { "description": "Tokens in the model's context window after the latest turn.", "type": [ "integer", "null" ] }, "window": { "description": "The model's context window size.", "type": [ "integer", "null" ] }, "percent": { "description": "Context occupancy 0-100, rounded.", "type": [ "integer", "null" ] } }, "required": [ "tokens", "window", "percent" ], "description": "Live context occupancy after the latest turn (not billing throughput)." }, "is_archived": { "type": "boolean" }, "session_type": { "type": "string", "enum": [ "session", "sidechat", "subagent" ], "description": "Session, sidechat fork, or read-only subagent Session." }, "source_session_id": { "description": "The fork source for a sidechat or spawning Session for a subagent; null for a normal Session.", "type": [ "string", "null" ] }, "read_only": { "type": "boolean", "description": "True only for subagent Sessions." }, "repos": { "type": "array", "items": { "type": "string" }, "description": "Every repository currently attached to the session, as owner/name. Present on Retrieve a session only, and only when recorded." }, "change_requests": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Pull request or merge request URL." }, "status": { "type": "string", "enum": [ "active", "completed", "retired" ] } }, "required": [ "url", "status" ] }, "description": "Every change request the session opened, including ones in repositories other than `repo`. Present on Retrieve a session only, and only when recorded." } } }, "SessionEvent": { "type": "object", "properties": { "id": { "type": "string" }, "seq": { "type": "integer", "description": "Monotonic event sequence number." }, "type": { "type": "string", "description": "With sessions:read this is always status. Diagnostic kinds require sessions:debug plus organization owner/admin." }, "text": { "description": "Null with sessions:read; raw diagnostic text requires sessions:debug plus organization owner/admin.", "type": [ "string", "null" ] }, "data": { "description": "Null with sessions:read; diagnostic metadata requires sessions:debug plus organization owner/admin.", "type": [ "object", "null" ], "properties": { "stream_key": { "type": "string" }, "item_id": { "type": "string" }, "tool": { "type": "string" }, "name": { "type": "string" }, "tool_use_id": { "type": "string" }, "stage": { "type": "string" }, "is_error": { "type": "boolean" } } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "seq" ] }, "SessionInsight": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "generated", "not_generated" ] }, "summary": { "type": "string", "description": "A short natural-language summary of what the session did." }, "category": { "type": "string", "description": "The inferred category of the work, e.g. `bug_fix` or `feature`." }, "outcome": { "type": "string", "description": "The outcome of the session, e.g. `pr_opened`." }, "message_count": { "type": "integer", "description": "Number of messages exchanged during the session." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Relative size of the change." }, "initial_user_message": { "description": "The first instruction that started the session.", "type": [ "string", "null" ] }, "pr_url": { "type": [ "string", "null" ] }, "cost_usd": { "type": [ "number", "null" ] }, "input_tokens": { "type": [ "integer", "null" ] }, "output_tokens": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "A generated summary of a session and its headline metrics. When `status` is `not_generated`, only `session_id` and `status` are populated." }, "Skill": { "type": "object", "properties": { "skill_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What the skill does and when an agent should use it. Ara uses this description for semantic selection." }, "instructions": { "type": "string" }, "activation_keywords": { "type": "array", "items": { "type": "string" }, "description": "Optional search aliases retained for compatibility. They do not activate the skill automatically." }, "is_enabled": { "type": "boolean" }, "author": { "type": "string" }, "provenance": { "type": "string", "enum": [ "authored", "skills_sh", "git", "agent_plugin", "curated_integration", "builtin" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TagList": { "type": "object", "properties": { "ok": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "Trigger": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "schedule", "github_event", "webhook" ] }, "enabled": { "type": "boolean" }, "schedule": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "cron", "every", "at", null ] }, "expression": { "description": "Cron expression, or the ISO run-at time for a one-time trigger.", "type": [ "string", "null" ] }, "every_seconds": { "type": [ "integer", "null" ] }, "next_run_at": { "format": "date-time", "type": [ "string", "null" ] } } }, "github": { "type": [ "object", "null" ], "properties": { "event": { "type": [ "string", "null" ] }, "action": { "type": [ "string", "null" ] }, "repo": { "type": [ "string", "null" ] } } }, "webhook": { "type": [ "object", "null" ], "properties": { "configured": { "type": "boolean" } } }, "run_kind": { "type": [ "string", "null" ] }, "last_fired_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "A condition that fires the automation. The webhook secret is never returned." }, "UpdateAutomation": { "type": "object", "properties": { "name": { "type": "string" }, "instructions": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "tools": { "type": "object", "properties": { "mcp_servers": { "description": "Org MCP server slugs this automation may use. `null` inherits every enabled org server.", "type": [ "array", "null" ], "items": { "type": "string" } }, "app_tools": { "type": "array", "items": { "type": "string" }, "description": "Catalog connector slugs (e.g. `linear`, `sentry`)." } } }, "enabled": { "type": "boolean", "description": "Set `false` to pause the automation. A paused automation's triggers never fire." } }, "description": "All fields optional. Only the fields you send are changed." }, "UpdateMemoryNote": { "type": "object", "properties": { "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "title": { "type": "string", "description": "Optional title. It is trimmed, defaults to 'Memory note' when blank, and must be at most 160 characters." }, "content": { "type": "string", "description": "When supplied, content must be non-empty after trimming and no more than 240 KiB UTF-8." } }, "required": [ "repo" ], "description": "Supply repo plus one or both editable fields." }, "UpdateNote": { "type": "object", "properties": { "name": { "type": "string" }, "trigger": { "type": "string" }, "body": { "type": "string" }, "scope": { "type": "string" }, "repo_filter": { "type": "string" } }, "description": "All fields optional. Only the fields you send are changed." }, "UpdateSkill": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "Describe what the skill does and when an agent should use it. Ara uses this description for semantic selection." }, "instructions": { "type": "string" }, "activation_keywords": { "type": "array", "items": { "type": "string" }, "description": "Optional search aliases retained for compatibility. They improve explicit search but do not activate the skill automatically." }, "is_enabled": { "type": "boolean" } }, "description": "All fields optional. Only supplied fields are changed." }, "UsageTimeseriesPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "sandbox_minutes": { "type": "number" }, "tokens": { "type": "integer" }, "sessions": { "type": "integer" } } }, "WikiDocument": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Provider-native repository path. GitHub uses `owner/name`; GitLab may include nested groups." }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown content." } } } } } } } }, "paths": { "/v3/deployment": { "get": { "operationId": "getDeployment", "tags": [ "Account" ], "summary": "Read backend deployment identity", "description": "Returns non-secret release metadata used to verify an exact backend deployment.\n\nScope: `deployment:read`", "responses": { "200": { "description": "The currently running backend release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "araApiKey": [ "deployment:read" ] } ] } }, "/v3/organizations": { "get": { "operationId": "listOrganizations", "tags": [ "Organizations" ], "summary": "List organizations", "description": "Returns the organizations the current principal can access.\n\nScope: `org:read`", "responses": { "200": { "description": "Organizations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "org:read" ] } ] }, "post": { "operationId": "createOrganization", "tags": [ "Organizations" ], "summary": "Create an organization", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganization" }, "example": { "name": "Acme Inc", "slug": "acme" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getOrganization", "tags": [ "Organizations" ], "summary": "Retrieve an organization", "responses": { "200": { "description": "The organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "org:read" ] } ], "description": "Scope: `org:read`" }, "patch": { "operationId": "updateOrganization", "tags": [ "Organizations" ], "summary": "Update an organization", "description": "Partial update. Send only the fields you want to change.\n\nScope: `org:write`", "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "example": { "name": "Acme Corporation" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ] }, "delete": { "operationId": "deleteOrganization", "tags": [ "Organizations" ], "summary": "Delete an organization", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}/agent-auth/models": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listAgentModels", "tags": [ "Agent Auth" ], "summary": "List Ara models", "description": "Returns Ara's reviewed model allowlist.\n\nScope: `agent_auth:read`", "responses": { "200": { "description": "Ara availability and reviewed models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentModelList" } } } } }, "security": [ { "araApiKey": [ "agent_auth:read" ] } ] } }, "/v3/organizations/{orgId}/agent-auth/status": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getAgentAuthStatus", "tags": [ "Agent Auth" ], "summary": "Get Ara inference availability", "description": "Reports whether Ara's managed inference service is available. No provider credentials are exposed.\n\nScope: `agent_auth:read`", "responses": { "200": { "description": "Ara inference availability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthStatus" } } } } }, "security": [ { "araApiKey": [ "agent_auth:read" ] } ] } }, "/v3/organizations/{orgId}/attachments": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listAttachments", "tags": [ "Attachments" ], "summary": "List attachments", "description": "Returns the files uploaded to the organization, newest first. Paginates by offset: pass `cursor` from the previous page's `end_cursor` to fetch the next page.\n\nScope: `attachments:read`", "responses": { "200": { "description": "Attachments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" } } }, "example": { "items": [ { "id": "att_7b1", "name": "spec.pdf", "content_type": "application/pdf", "size_bytes": 88213, "url": "https://...", "created_at": "2026-06-23T20:10:00Z" } ], "end_cursor": null, "has_next_page": false } } } } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 }, "description": "Page size (default 50, max 100)." }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Offset cursor from the previous page's `end_cursor`." } ], "security": [ { "araApiKey": [ "attachments:read" ] } ] }, "post": { "operationId": "createAttachment", "tags": [ "Attachments" ], "summary": "Upload an attachment", "description": "Uploads a file to the organization. Send the file as `multipart/form-data` in the `file` field.\n\nScope: `attachments:write`", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload." } } } } } }, "responses": { "201": { "description": "The created attachment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "araApiKey": [ "attachments:write" ] } ] } }, "/v3/organizations/{orgId}/attachments/{attachmentId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "attachmentId", "description": "The attachment id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "downloadAttachment", "tags": [ "Attachments" ], "summary": "Download an attachment", "description": "Redirects (307) to a short-lived signed download URL for the attachment.\n\nScope: `attachments:read`", "responses": { "307": { "description": "Redirect to the attachment's signed download URL." }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "attachments:read" ] } ] } }, "/v3/organizations/{orgId}/attachments/{attachmentId}/{filename}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "attachmentId", "description": "The attachment id.", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "filename", "description": "Cosmetic filename for the downloaded file; not validated against the stored name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "downloadAttachmentWithFilename", "tags": [ "Attachments" ], "summary": "Download an attachment (named)", "description": "Same 307 redirect as the bare download route; the trailing filename gives naive clients the right file name.\n\nScope: `attachments:read`", "responses": { "307": { "description": "Redirect to the attachment's signed download URL." }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "attachments:read" ] } ] } }, "/v3/organizations/{orgId}/audit-logs": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listAuditLogs", "tags": [ "Audit Logs" ], "summary": "List audit log entries", "description": "Returns audit log entries newest first.\n\nScope: `analytics:read`", "responses": { "200": { "description": "Audit log entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "has_next_page": { "type": "boolean" }, "end_cursor": { "description": "Pass back as `after` for the next page.", "type": [ "string", "null" ] }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" }, "description": "Legacy twin of `items`." }, "next_before": { "description": "Legacy twin of `end_cursor`.", "type": [ "string", "null" ] } } } } } } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 }, "description": "Maximum entries to return (default 50, max 200)." }, { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" }, "description": "Return only entries created before this timestamp." }, { "in": "query", "name": "action", "schema": { "type": "string" }, "description": "Return only entries with this exact action." }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "Return only entries performed by this actor user id." }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" }, "description": "Return only entries created at or after this ISO timestamp." } ], "security": [ { "araApiKey": [ "analytics:read" ] } ] } }, "/v3/organizations/{orgId}/automations": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listAutomations", "tags": [ "Automations" ], "summary": "List automations", "description": "User-authored automations in the workspace, each with its triggers. System automations (repo/issue plumbing, connector bridges) are excluded by default; pass `include=system` to return them too. An automation with no triggers is included; it simply never fires on its own.\n\nScope: `automations:read`", "responses": { "200": { "description": "Automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } }, "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" } } } } } } }, "parameters": [ { "in": "query", "name": "first", "schema": { "type": "integer", "default": 50 }, "description": "Page size (default 50, max 200)." }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor from the previous page's `end_cursor`." }, { "in": "query", "name": "include", "schema": { "type": "string", "enum": [ "system" ] }, "description": "By default only user-authored automations are returned. Pass `system` to also include system automations (repo/issue plumbing, connector bridges) that back product features." } ], "security": [ { "araApiKey": [ "automations:read" ] } ] }, "post": { "operationId": "createAutomation", "tags": [ "Automations" ], "summary": "Create an automation", "description": "Creates the automation's configuration (instructions + environment binding). Add a trigger with `POST /automations/{automationId}/triggers` to make it fire. The repo must already be connected.\n\nScope: `automations:write`", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Available during an Ara trial or paid subscription." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomation" }, "example": { "name": "Nightly dependency audit", "instructions": "Audit dependencies for known CVEs and open a PR if any need patching.", "repo": "acme/widget", "provider": "github" } } } }, "security": [ { "araApiKey": [ "automations:write" ] } ] } }, "/v3/organizations/{orgId}/automations/{automationId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getAutomation", "tags": [ "Automations" ], "summary": "Retrieve an automation", "responses": { "200": { "description": "The automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "automations:read" ] } ], "description": "Scope: `automations:read`" }, "patch": { "operationId": "updateAutomation", "tags": [ "Automations" ], "summary": "Update an automation", "description": "Partial update of the automation's configuration. Send only the fields you want to change. Triggers are managed through the triggers sub-resource.\n\nScope: `automations:write`", "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "402": { "description": "Available during an Ara trial or paid subscription." }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomation" } } } }, "security": [ { "araApiKey": [ "automations:write" ] } ] }, "delete": { "operationId": "deleteAutomation", "tags": [ "Automations" ], "summary": "Delete an automation", "description": "Deletes the automation and removes its triggers. Idempotent.\n\nScope: `automations:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "automations:write" ] } ] } }, "/v3/organizations/{orgId}/automations/{automationId}/triggers": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listAutomationTriggers", "tags": [ "Automations" ], "summary": "List an automation's triggers", "responses": { "200": { "description": "Triggers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Trigger" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "automations:read" ] } ], "description": "Scope: `automations:read`" }, "post": { "operationId": "createAutomationTrigger", "tags": [ "Automations" ], "summary": "Add a trigger to an automation", "description": "Provide exactly one schedule: a `frequency` cron expression for recurring runs, `every_seconds` for a fixed interval, or a `scheduled_at` timestamp for a one-time run.\n\nScope: `automations:write`", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trigger" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrigger" }, "example": { "frequency": "0 3 * * *" } } } }, "security": [ { "araApiKey": [ "automations:write" ] } ] } }, "/v3/organizations/{orgId}/automations/{automationId}/triggers/{triggerId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "triggerId", "description": "The trigger id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteAutomationTrigger", "tags": [ "Automations" ], "summary": "Remove a trigger from an automation", "description": "Idempotent. The automation itself is untouched; it simply stops firing on that condition.\n\nScope: `automations:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "automations:write" ] } ] } }, "/v3/organizations/{orgId}/consumption/daily": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getDailyConsumption", "tags": [ "Consumption" ], "summary": "Get daily consumption", "description": "Returns usage broken down by day over a date range.\n\nScope: `analytics:read`", "responses": { "200": { "description": "Daily consumption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "daily": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionDay" }, "description": "Per-day series (ungrouped requests)." }, "items": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Per-key totals. Present instead of `daily` when `group_by` is set." }, "total": { "type": "object", "properties": { "spend_usd": { "type": "number" }, "credits_usd": { "type": "number" }, "sandbox_minutes": { "type": "number" } } }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } } } } } }, "parameters": [ { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "Inclusive start date (`YYYY-MM-DD`)." }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "Inclusive end date (`YYYY-MM-DD`)." }, { "in": "query", "name": "group_by", "schema": { "type": "string", "enum": [ "session", "user" ] }, "description": "Optional dimension to group by. Unknown values fall back to the ungrouped daily series." } ], "security": [ { "araApiKey": [ "analytics:read" ] } ] } }, "/v3/organizations/{orgId}/git-connections": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listGitConnections", "deprecated": true, "tags": [ "Git Connections" ], "summary": "List git connections (deprecated)", "description": "Deprecated. Use `GET /git-plugins` instead.\n\nScope: `repos:read`", "responses": { "200": { "description": "Git connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitConnection" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/git-connections/{gitConnectionId}/repositories": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "gitConnectionId", "description": "Deprecated git connection id. Use gitPluginId on the canonical git-plugins routes.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listGitConnectionRepositories", "deprecated": true, "tags": [ "Git Connections" ], "summary": "List repositories for a git connection (deprecated)", "description": "Deprecated. Use `GET /git-plugins/{gitPluginId}/repositories` instead.\n\nScope: `repos:read`", "responses": { "200": { "description": "Repositories for the connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitConnectionRepository" } }, "total": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/git-plugins": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listGitPlugins", "tags": [ "Git Plugins" ], "summary": "List git plugins", "description": "Returns the source-control accounts linked to the organization.\n\nScope: `repos:read`", "responses": { "200": { "description": "Git plugins.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/GitPlugin" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/git-plugins/{gitPluginId}/repositories": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "gitPluginId", "description": "The git plugin id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listGitPluginRepositories", "tags": [ "Git Plugins" ], "summary": "List repositories for a git plugin", "description": "Returns the repositories exposed by a linked source-control plugin.\n\nScope: `repos:read`", "responses": { "200": { "description": "Repositories for the plugin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitPluginRepository" } }, "total": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/indexed-repositories": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listIndexedRepositories", "tags": [ "Repositories" ], "summary": "List indexed repositories", "description": "Returns repositories that have been indexed for wiki generation and code understanding.\n\nScope: `repos:read`", "responses": { "200": { "description": "Indexed repositories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IndexedRepository" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/knowledge/folders": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listKnowledgeFolders", "tags": [ "Knowledge" ], "summary": "List knowledge folders", "description": "The folder structure with note counts, derived from each note's scope.\n\nScope: `knowledge:read`", "responses": { "200": { "description": "Folders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeFolder" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "knowledge:read" ] } ] } }, "/v3/organizations/{orgId}/knowledge/notes": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listNotes", "tags": [ "Knowledge" ], "summary": "List notes", "responses": { "200": { "description": "Knowledge notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "knowledge:read" ] } ], "description": "Scope: `knowledge:read`" }, "post": { "operationId": "createNote", "tags": [ "Knowledge" ], "summary": "Create a note", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNote" }, "example": { "name": "Deploy process", "trigger": "When deploying to production", "body": "Run `bun run release` and wait for the green check before merging." } } } }, "security": [ { "araApiKey": [ "run" ] } ], "description": "Scope: `run`" } }, "/v3/organizations/{orgId}/knowledge/notes/{noteId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getNote", "tags": [ "Knowledge" ], "summary": "Retrieve a note", "responses": { "200": { "description": "The note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "knowledge:read" ] } ], "description": "Scope: `knowledge:read`" }, "put": { "operationId": "updateNote", "tags": [ "Knowledge" ], "summary": "Update a note", "description": "Partial update. Send only the fields you want to change.\n\nScope: `run`", "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNote" } } } }, "security": [ { "araApiKey": [ "run" ] } ] }, "delete": { "operationId": "deleteNote", "tags": [ "Knowledge" ], "summary": "Delete a note", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "run" ] } ], "description": "Scope: `run`" } }, "/v3/organizations/{orgId}/mcp-servers": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listMcpServers", "tags": [ "MCP Servers" ], "summary": "List MCP servers", "description": "Returns the org-level MCP servers exposed to the agent. Secret values are never returned.\n\nScope: `mcp:read`", "responses": { "200": { "description": "MCP servers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/McpServer" } }, "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "mcp:read" ] } ] }, "post": { "operationId": "createMcpServer", "tags": [ "MCP Servers" ], "summary": "Create an MCP server", "description": "Registers an org-level MCP server. Secret values supplied in `secrets` are stored write-only and never returned.\n\nScope: `mcp:write`", "responses": { "201": { "description": "The created MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerInput" } } } }, "security": [ { "araApiKey": [ "mcp:write" ] } ] } }, "/v3/organizations/{orgId}/mcp-servers/{id}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "id", "description": "The MCP server id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getMcpServer", "tags": [ "MCP Servers" ], "summary": "Retrieve an MCP server", "description": "Returns a single org-level MCP server. Secret values are never returned.\n\nScope: `mcp:read`", "responses": { "200": { "description": "The MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "mcp:read" ] } ] }, "patch": { "operationId": "updateMcpServer", "tags": [ "MCP Servers" ], "summary": "Update an MCP server", "description": "Partial update. Send only the fields you want to change. Secret values are stored write-only and never returned.\n\nScope: `mcp:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerInput" } } } }, "responses": { "200": { "description": "The updated MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "mcp:write" ] } ] }, "delete": { "operationId": "deleteMcpServer", "tags": [ "MCP Servers" ], "summary": "Delete an MCP server", "description": "Removes an org-level MCP server.\n\nScope: `mcp:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "mcp:write" ] } ] } }, "/v3/organizations/{orgId}/members/users": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listMembers", "tags": [ "Members" ], "summary": "List members", "description": "Returns the people in the organization.\n\nScope: `org:read`", "responses": { "200": { "description": "Members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "total": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "end_cursor": { "type": "null" }, "invites": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" }, "description": "Pending invitations. Present only for owner/admin callers." } } } } } } }, "security": [ { "araApiKey": [ "org:read" ] } ] }, "post": { "operationId": "inviteMember", "tags": [ "Members" ], "summary": "Invite a member", "description": "Sends invitations to join the organization with the given role.\n\nScope: `org:write`", "responses": { "200": { "description": "Invitations created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invited": { "type": "integer", "description": "How many invitations were created." } } }, "example": { "invited": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Email addresses to invite." }, "role": { "type": "string", "enum": [ "admin", "member" ], "default": "admin", "description": "Omitted values invite an admin; unknown values coerce to `member`." } }, "required": [ "emails" ] }, "example": { "emails": [ "engineer@acme.com" ], "role": "admin" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ] } }, "/v3/organizations/{orgId}/members/users/{userId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "userId", "description": "The member's user id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getMember", "tags": [ "Members" ], "summary": "Get a member", "responses": { "200": { "description": "The member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "org:read" ] } ], "description": "Scope: `org:read`" }, "delete": { "operationId": "removeMember", "tags": [ "Members" ], "summary": "Remove a member", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}/members/users/{userId}/role": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "userId", "description": "The member's user id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "operationId": "setMemberRole", "tags": [ "Members" ], "summary": "Set a member's role", "responses": { "200": { "description": "Role updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } } }, "example": { "user_id": "usr_4a1b", "role": "admin" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "`owner` may only be granted by an org owner." } }, "required": [ "role" ] }, "example": { "role": "admin" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}/memory/notes": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listMemoryNotes", "tags": [ "Memory" ], "summary": "List repository memory notes", "description": "Lists editable notes for one connected repository. Generated native memory is intentionally not included.\n\nScope: `memory:read`", "responses": { "200": { "description": "Memory notes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryNoteList" } } } } }, "parameters": [ { "in": "query", "name": "repo", "schema": { "type": "string" }, "required": true, "description": "Provider-native repository path (for example owner/repo)." }, { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ] }, "description": "Source-control provider. Required when this path exists on more than one provider." } ], "security": [ { "araApiKey": [ "memory:read" ] } ] }, "post": { "operationId": "createMemoryNote", "tags": [ "Memory" ], "summary": "Create a repository memory note", "description": "Creates an explicit note immediately. Ara materializes it into the native append-only note extension before the next cold, memory-enabled run. Generated native memory remains read-only.\n\nScope: `memory:write`", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryNoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoryNote" }, "example": { "repo": "acme/web", "provider": "github", "title": "Release preferences", "content": "Run the full test suite before opening a release pull request." } } } }, "security": [ { "araApiKey": [ "memory:write" ] } ] } }, "/v3/organizations/{orgId}/memory/notes/{memoryId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "memoryId", "description": "The repository memory note id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getMemoryNote", "tags": [ "Memory" ], "summary": "Retrieve a repository memory note", "responses": { "200": { "description": "Memory note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryNoteResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "repo", "schema": { "type": "string" }, "required": true, "description": "Provider-native repository path (for example owner/repo)." }, { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ] }, "description": "Source-control provider. Required when this path exists on more than one provider." } ], "security": [ { "araApiKey": [ "memory:read" ] } ], "description": "Scope: `memory:read`" }, "patch": { "operationId": "updateMemoryNote", "tags": [ "Memory" ], "summary": "Update a repository memory note", "description": "Updates the explicit note immediately and records a new native append-only revision for the next cold, memory-enabled run. Generated native memory remains read-only.\n\nScope: `memory:write`", "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryNoteResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryNote" } } } }, "security": [ { "araApiKey": [ "memory:write" ] } ] }, "delete": { "operationId": "forgetMemoryNote", "tags": [ "Memory" ], "summary": "Forget a repository memory note", "description": "Hides the editable note immediately and records a native forget event for the next cold, memory-enabled run; historic native note files remain append-only by design.\n\nScope: `memory:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "repo", "schema": { "type": "string" }, "required": true, "description": "Provider-native repository path (for example owner/repo)." }, { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ] }, "description": "Source-control provider. Required when this path exists on more than one provider." } ], "security": [ { "araApiKey": [ "memory:write" ] } ] } }, "/v3/organizations/{orgId}/metrics/usage": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getUsageMetrics", "tags": [ "Metrics" ], "summary": "Get usage metrics", "description": "Returns a usage time series, such as sandbox minutes and tokens per day.\n\nScope: `analytics:read`", "responses": { "200": { "description": "Usage time series.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageTimeseriesPoint" } } } } } } } }, "security": [ { "araApiKey": [ "analytics:read" ] } ] } }, "/v3/organizations/{orgId}/onboarding/import/complete": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "completeOnboardingImport", "tags": [ "Onboarding" ], "summary": "Mark an approved local secret import complete", "responses": { "200": { "description": "Import recorded.", "content": { "application/json": { "example": { "status": "completed" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteOnboardingImportRequest" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}/onboarding/import/decision": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "getOnboardingImportDecision", "tags": [ "Onboarding" ], "summary": "Poll the browser's local secret import decision", "description": "Returns only the approved secret names. Values remain local to the CLI until approval.\n\nScope: `org:write`", "responses": { "200": { "description": "The current handoff decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingImportDecision" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingImportDecisionRequest" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ] } }, "/v3/organizations/{orgId}/onboarding/import/pairing/claim-existing": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "claimExistingCliPairing", "tags": [ "Onboarding" ], "summary": "Attach an existing CLI grant to a browser pairing", "responses": { "200": { "description": "Pairing claimed by the current CLI grant." }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimCliPairingRequest" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}/onboarding/import/pairing/failure": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "reportCliPairingFailure", "tags": [ "Onboarding" ], "summary": "Report that a paired local scan could not finish", "responses": { "200": { "description": "Failure recorded." }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliPairingFailureRequest" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ], "description": "Scope: `org:write`" } }, "/v3/organizations/{orgId}/onboarding/import/summary": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "createOnboardingImportHandoff", "tags": [ "Onboarding" ], "summary": "Create a local onboarding import handoff", "description": "Creates a short-lived browser handoff containing secret names and coarse source descriptions. Secret values and local paths are never accepted.\n\nScope: `org:write`", "responses": { "200": { "description": "A short-lived opaque browser handoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingImportHandoff" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingImportSummary" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ] } }, "/v3/organizations/{orgId}/pr-reviews": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listPrReviews", "tags": [ "Change Request Reviews" ], "summary": "List change request reviews", "description": "Returns the latest automated pull request or merge request reviews, newest first, cursor-paginated.\n\nScope: `reviews:read`", "responses": { "200": { "description": "A page of change request reviews.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrReview" } }, "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "in": "query", "name": "first", "schema": { "type": "integer", "default": 50 }, "description": "Page size (default 50, max 200)." }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor from the previous page's `end_cursor`." } ], "security": [ { "araApiKey": [ "reviews:read" ] } ] }, "post": { "operationId": "triggerPrReview", "tags": [ "Change Request Reviews" ], "summary": "Trigger a change request review", "description": "Queues an automated review of a pull request or merge request. Provide `repository` and `pr_number`, or provide `pr_url`; add optional `provider` and `instructions`.\n\nScope: `reviews:write`", "responses": { "201": { "description": "Review queued.", "content": { "application/json": { "example": { "pr_review_id": "rev_71c2a8", "status": "queued" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Quota exhausted for the billing account.", "content": { "application/json": { "example": { "error": "quota_exhausted", "message": "Monthly review quota exceeded." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrReview" }, "example": { "repository": "acme/web", "pr_number": 482, "provider": "github", "instructions": "Pay special attention to the new auth middleware." } } } }, "security": [ { "araApiKey": [ "reviews:write" ] } ] } }, "/v3/organizations/{orgId}/queue": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getQueueStatus", "tags": [ "Metrics" ], "summary": "Get queue status", "description": "Returns the current run queue: workspace and per-repo running/queued counts plus the running and queued runs.\n\nScope: `analytics:read`", "responses": { "200": { "description": "Queue status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "running": { "type": "integer" }, "queued": { "type": "integer" } } }, "per_repo": { "type": "array", "items": { "type": "object", "properties": { "repo": { "type": "string" }, "running": { "type": "integer" }, "queued": { "type": "integer" }, "max_concurrent": { "type": "integer" } } } }, "running_runs": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string" }, "repo": { "type": "string" }, "agent_id": { "type": "string" }, "run_kind": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" } } } }, "queued_runs": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string" }, "repo": { "type": "string" }, "agent_id": { "type": "string" }, "run_kind": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "position": { "type": "integer" } } } } } } } } } }, "security": [ { "araApiKey": [ "analytics:read" ] } ] } }, "/v3/organizations/{orgId}/repositories": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listRepositories", "tags": [ "Repositories" ], "summary": "List repositories", "description": "Returns repositories the organization can connect agents to.\n\nScope: `repos:read`", "responses": { "200": { "description": "Repositories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Repository" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/repositories/bulk-index": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "put": { "operationId": "bulkIndexRepositories", "tags": [ "Repositories" ], "summary": "Bulk index repositories", "description": "Starts indexing for many repositories at once. Each entry may be an `owner/name` string or an `{ owner, repo }` object. Returns a per-repository result so partial failures are visible.\n\nScope: `repos:write`", "responses": { "200": { "description": "Per-repository results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkRepoResult" } } } }, "example": { "results": [ { "repo": "acme/web", "status": "indexing" }, { "repo": "acme/api", "status": "error", "error": "not_connected" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Available during an Ara trial or paid subscription." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRepoRequest" }, "example": { "repositories": [ "acme/web", { "owner": "group", "repo": "subgroup/project", "provider": "gitlab" } ] } } } }, "security": [ { "araApiKey": [ "repos:write" ] } ] } }, "/v3/organizations/{orgId}/repositories/bulk-remove": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "delete": { "operationId": "bulkRemoveRepositories", "tags": [ "Repositories" ], "summary": "Bulk remove repositories", "description": "Disconnects many repositories at once and removes their indexes. Each entry may be an `owner/name` string or an `{ owner, repo }` object. Returns a per-repository result so partial failures are visible.\n\nScope: `repos:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRepoRequest" }, "example": { "repositories": [ "acme/web", { "owner": "acme", "repo": "api" } ] } } } }, "responses": { "200": { "description": "Per-repository results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkRepoResult" } } } }, "example": { "results": [ { "repo": "acme/web", "status": "removed" }, { "repo": "acme/api", "status": "error", "error": "not_found" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "repos:write" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteRepository", "tags": [ "Repositories" ], "summary": "Disconnect a repository", "description": "Disconnects the repository from the organization and removes its index.\n\nScope: `repos:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "repos:write" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}/branches/{branch}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "branch", "description": "Branch name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteRepositoryBranch", "tags": [ "Repositories" ], "summary": "Delete a repository branch", "description": "Deletes a branch from the connected repository.\n\nScope: `repos:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "repos:write" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}/guardrails": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getRepositoryGuardrails", "tags": [ "Repositories" ], "summary": "Get repository guardrails", "description": "Returns the automation guardrails configured for a repository.\n\nScope: `guardrails:read`", "responses": { "200": { "description": "The repository guardrails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "guardrails": { "$ref": "#/components/schemas/Guardrails" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "guardrails:read" ] } ] }, "put": { "operationId": "updateRepositoryGuardrails", "tags": [ "Repositories" ], "summary": "Update repository guardrails", "description": "Partial update. Send only the guardrail fields you want to change.\n\nScope: `guardrails:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Guardrails" } } } }, "responses": { "200": { "description": "The updated repository guardrails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "guardrails": { "$ref": "#/components/schemas/Guardrails" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Available during an Ara trial or paid subscription." }, "403": { "$ref": "#/components/responses/Forbidden" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "guardrails:write" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}/index": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "operationId": "indexRepository", "tags": [ "Repositories" ], "summary": "Index a repository", "description": "Starts (or restarts) indexing the repository for wiki generation and code understanding. Returns immediately; poll the indexing status to follow progress.\n\nScope: `repos:write`", "responses": { "200": { "description": "Indexing started.", "content": { "application/json": { "example": { "ok": true, "owner": "acme", "repo": "web", "status": "indexing" } } } }, "402": { "description": "Available during an Ara trial or paid subscription." }, "403": { "description": "The key lacks access, or the repository was enabled but the GitLab account cannot manage its webhook.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RepositoryProvisionFailure" } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The repository path conflicts with another provider, or the GitLab connection must be repaired.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryProvisionFailure" }, { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "repo_path_provider_conflict" ] }, "message": { "type": "string" } } } ] } } } }, "500": { "description": "The repository was enabled, but agent provisioning did not complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryProvisionFailure" } } } }, "502": { "description": "The repository was enabled, but GitLab webhook provisioning failed upstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryProvisionFailure" } } } }, "503": { "description": "The repository was enabled, but GitLab webhook provisioning is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryProvisionFailure" } } } } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "repos:write" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}/indexing-status": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getIndexingStatus", "tags": [ "Repositories" ], "summary": "Get indexing status", "description": "Reports whether the repository is indexed and how far along the current indexing run is.\n\nScope: `repos:read`", "responses": { "200": { "description": "Indexing status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexingStatus" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}/wiki": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getRepositoryWiki", "tags": [ "Repositories" ], "summary": "Get repository wiki", "description": "Returns the generated wiki for an indexed repository.\n\nScope: `repos:read`", "responses": { "200": { "description": "The repository wiki.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiDocument" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." } ], "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/repositories/{owner}/{repo}/wiki/export": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "owner", "description": "Repository owner (user or organization).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "description": "Repository name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "exportRepositoryWiki", "tags": [ "Repositories" ], "summary": "Export repository wiki", "description": "Returns the entire generated wiki for an indexed repository as a single document: consolidated Markdown by default, or a structured JSON bundle with `?format=json`.\n\nScope: `repos:read`", "responses": { "200": { "description": "The exported wiki.", "content": { "text/markdown": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "properties": { "repository": { "type": "string" }, "page_count": { "type": "integer" } } }, "pages": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ], "default": "github" }, "description": "Source-control provider to use when the same repository path exists on more than one connected provider." }, { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" }, "description": "`markdown` returns the whole wiki as one Markdown document; `json` returns a structured bundle of the ordered pages." } ], "security": [ { "araApiKey": [ "repos:read" ] } ] } }, "/v3/organizations/{orgId}/roles": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listRoleAssignments", "deprecated": true, "tags": [ "Roles" ], "summary": "List role assignments (retired)", "description": "Retired. Platform-wide role administration is not available.\n\nScope: `org:read`", "responses": { "200": { "description": "Historical role assignment response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } }, "total": { "type": "integer" } } } } } }, "410": { "description": "This endpoint has been retired." } }, "security": [ { "araApiKey": [ "org:read" ] } ] }, "put": { "operationId": "setRoleAssignment", "deprecated": true, "tags": [ "Roles" ], "summary": "Set a role assignment (retired)", "description": "Retired. Platform-wide role administration is not available.\n\nScope: `org:write`", "responses": { "200": { "description": "Historical role assignment response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "This endpoint has been retired." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Target user id. Provide either `user_id` or `email`." }, "email": { "type": "string", "description": "Target user email, resolved to the user. Alternative to `user_id`." }, "role": { "type": "string", "enum": [ "pro", "regular" ], "description": "App-level product role." } }, "required": [ "role" ] }, "example": { "user_id": "usr_4a1b", "role": "pro" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ] } }, "/v3/organizations/{orgId}/roles/me": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getOwnRole", "tags": [ "Roles" ], "summary": "Get the caller's role", "description": "Returns the calling principal's product role.\n\nScope: `org:read`", "responses": { "200": { "description": "The caller's role assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } } }, "security": [ { "araApiKey": [ "org:read" ] } ] } }, "/v3/organizations/{orgId}/roles/{userId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "userId", "description": "The member's user id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getRoleAssignment", "deprecated": true, "tags": [ "Roles" ], "summary": "Get a role assignment (retired)", "description": "Retired. Platform-wide role administration is not available.\n\nScope: `org:read`", "responses": { "200": { "description": "Historical role assignment response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "This endpoint has been retired." } }, "security": [ { "araApiKey": [ "org:read" ] } ] } }, "/v3/organizations/{orgId}/secrets": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listSecrets", "tags": [ "Secrets" ], "summary": "List secret names", "description": "Lists secret names and metadata. Values are never returned.\n\nScope: `secrets:read`", "responses": { "200": { "description": "Secret names.", "content": { "application/json": { "example": { "items": [ { "secret_id": "NPM_TOKEN", "name": "NPM_TOKEN", "scope": "user", "created_at": "2026-06-01T00:00:00Z", "updated_at": "2026-06-01T00:00:00Z" } ], "end_cursor": null, "has_next_page": false } } } } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "organization", "user", "repo" ], "default": "user" } }, { "in": "query", "name": "repo", "schema": { "type": "string" }, "description": "Deprecated context field for the `repo` compatibility scope. The repository no longer changes storage; the secret is workspace-wide." }, { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ] }, "description": "Deprecated provider context for the `repo` compatibility scope." } ], "security": [ { "araApiKey": [ "secrets:read" ] } ] }, "post": { "operationId": "setSecret", "tags": [ "Secrets" ], "summary": "Create or update a secret", "responses": { "201": { "description": "Secret stored.", "content": { "application/json": { "example": { "ok": true, "name": "NPM_TOKEN", "scope": "user" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecret" }, "example": { "name": "NPM_TOKEN", "value": "npm_...", "note": "Used by acme/web", "scope": "organization" } } } }, "security": [ { "araApiKey": [ "secrets:write" ] } ], "description": "Scope: `secrets:write`" } }, "/v3/organizations/{orgId}/secrets/bulk": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "setOrganizationSecretsBulk", "tags": [ "Secrets" ], "summary": "Create or update workspace secrets in a batch", "description": "Stores a confirmed batch of workspace secrets encrypted. Values are never returned.\n\nScope: `secrets:write`", "responses": { "200": { "description": "Secrets stored.", "content": { "application/json": { "example": { "ok": true, "scope": "organization", "count": 2 } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationSecretsBulk" }, "example": { "variables": [ { "name": "NPM_TOKEN", "value": "npm_...", "note": "acme-web ยท .env.local" } ] } } } }, "security": [ { "araApiKey": [ "secrets:write" ] } ] } }, "/v3/organizations/{orgId}/secrets/{secretId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "secretId", "description": "The secret name.", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteSecret", "tags": [ "Secrets" ], "summary": "Delete a secret", "responses": { "200": { "$ref": "#/components/responses/Ok" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "organization", "user", "repo" ], "default": "user" } }, { "in": "query", "name": "repo", "schema": { "type": "string" }, "description": "Deprecated context field for the `repo` compatibility scope. The repository no longer changes storage; the secret is workspace-wide." }, { "in": "query", "name": "provider", "schema": { "type": "string", "enum": [ "github", "gitlab" ] }, "description": "Deprecated provider context for the `repo` compatibility scope." } ], "security": [ { "araApiKey": [ "secrets:write" ] } ], "description": "Scope: `secrets:write`" } }, "/v3/organizations/{orgId}/sessions": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listSessions", "tags": [ "Sessions" ], "summary": "List sessions", "description": "Returns Sessions newest first, cursor-paginated. Follow-up execution Attempts update their Session and never appear as additional list items.\n\nScope: `sessions:read`", "responses": { "200": { "description": "A page of sessions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "in": "query", "name": "first", "schema": { "type": "integer", "default": 50 }, "description": "Page size (default 50, max 200)." }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor from the previous page's `end_cursor`." } ], "security": [ { "araApiKey": [ "sessions:read" ] } ] }, "post": { "operationId": "createSession", "tags": [ "Sessions" ], "summary": "Create a session", "description": "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.\n\nScope: `run`", "responses": { "201": { "description": "Session created and queued.", "content": { "application/json": { "example": { "session_id": "ses_91af3c", "url": "https://ara.so/org/acme/sessions/ses_91af3c", "status": "running" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Quota exhausted for the billing account.", "content": { "application/json": { "example": { "error": "quota_exhausted", "message": "Monthly sandbox minutes exceeded." } } } }, "503": { "description": "Temporarily unable to create the session: model credential preflight could not be completed, or `env` was supplied while the deployment's secret store is unavailable (`secret_store_unavailable`)." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSession" }, "example": { "prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.", "repo": "acme/web", "provider": "github", "tags": [ "ci", "tests" ] } } } }, "security": [ { "araApiKey": [ "run" ] } ] } }, "/v3/organizations/{orgId}/sessions/insights": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listSessionsWithInsights", "tags": [ "Sessions" ], "summary": "List sessions with insights", "description": "Pages sessions like `GET /sessions` and attaches each session's stored insight (or a `not_generated` placeholder). Nothing is generated by this call.\n\nScope: `sessions:read`", "responses": { "200": { "description": "A page of sessions, each carrying an `insight` object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" } } } } } } }, "parameters": [ { "in": "query", "name": "first", "schema": { "type": "integer", "default": 50 }, "description": "Page size (default 50, max 200)." }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor from the previous page's `end_cursor`." } ], "security": [ { "araApiKey": [ "sessions:read" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSession", "tags": [ "Sessions" ], "summary": "Retrieve a session", "description": "Returns the stable Session identity with current execution state. A previously returned physical Attempt UUID remains accepted as a compatibility alias, but the response always carries the Session `session_id` and URL.\n\nScope: `sessions:read`", "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "sessions:read" ] } ] }, "delete": { "operationId": "deleteSession", "tags": [ "Sessions" ], "summary": "Delete a session", "description": "Permanently deletes the session. Set `?archive=true` to preserve it (archive) instead.\n\nScope: `run`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "archive", "schema": { "type": "boolean" }, "description": "When `true`, archive the session instead of deleting it." } ], "security": [ { "araApiKey": [ "run" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/archive": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "archiveSession", "tags": [ "Sessions" ], "summary": "Archive a session", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Deletion is temporarily blocked while inference usage is awaiting settlement.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "reason", "message" ], "properties": { "error": { "type": "string", "enum": [ "session_delete_blocked" ] }, "reason": { "type": "string", "enum": [ "inference_reconciliation_pending" ] }, "message": { "type": "string" } } } } } } }, "security": [ { "araApiKey": [ "run" ] } ], "description": "Scope: `run`" } }, "/v3/organizations/{orgId}/sessions/{sessionId}/attachments": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listSessionAttachments", "tags": [ "Sessions" ], "summary": "List attachments", "description": "Artifacts produced by the session: diffs, logs, screenshots, and build outputs.\n\nScope: `sessions:read`", "responses": { "200": { "description": "The session's attachments.", "content": { "application/json": { "example": { "session_id": "ses_91af3c", "items": [ { "id": "att_1", "name": "diff.patch", "kind": "diff", "content_type": "text/plain", "size_bytes": 4210, "url": "https://...", "created_at": "2026-06-23T20:10:00Z" } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "sessions:read" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/attachments/{attachmentId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "description": "The attachment id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSessionAttachment", "tags": [ "Sessions" ], "summary": "Download an attachment", "description": "Redirects (307) to a download URL for the attachment.\n\nScope: `sessions:read`", "responses": { "307": { "description": "Redirect to the attachment's download URL." }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "sessions:read" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/cancel": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "cancelSession", "tags": [ "Sessions" ], "summary": "Cancel a session", "description": "Requests cancellation of a running session. Returns whether the request was newly flagged.\n\nScope: `run`", "responses": { "200": { "description": "Cancellation requested.", "content": { "application/json": { "example": { "ok": true, "requested": true, "status": "running" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "run" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/events": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listSessionEvents", "tags": [ "Sessions" ], "summary": "List live session events", "description": "Poll incremental agent activity. Pass the previous `next_seq` as `after_seq` to receive only newer events. `sessions:read` returns status events with null text/data. An organization owner/admin may add `sessions:debug` for the full diagnostic projection, including reasoning and tool results.\n\nScope: `sessions:read`", "responses": { "200": { "description": "The current session plus a bounded page of live events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/Session" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SessionEvent" } }, "next_seq": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "after_seq", "schema": { "type": "integer" }, "description": "Return only events whose monotonic sequence number is higher than this value. Use -1 to start before event zero." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 200 }, "description": "Maximum events to return (default 200, max 1000)." } ], "security": [ { "araApiKey": [ "sessions:read" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/insights": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSessionInsight", "tags": [ "Sessions" ], "summary": "Get session insights", "description": "Returns the generated insight for a session: a summary, category, outcome, and headline metrics. If no insight has been generated yet, `status` is `not_generated` and the detail fields are absent.\n\nScope: `sessions:read`", "responses": { "200": { "description": "The session insight, or a `not_generated` placeholder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionInsight" }, "example": { "session_id": "ses_91af3c", "status": "generated", "summary": "Fixed the flaky auth-session test and added a regression case.", "category": "bug_fix", "outcome": "pr_opened", "message_count": 14, "size": "small", "initial_user_message": "Fix the flaky test in src/auth/session.test.ts and add a regression case.", "pr_url": "https://github.com/acme/web/pull/482", "cost_usd": 0.42, "input_tokens": 184200, "output_tokens": 21050, "generated_at": "2026-06-23T20:30:00Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "sessions:read" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/insights/generate": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "generateSessionInsight", "tags": [ "Sessions" ], "summary": "Generate session insights", "description": "Generates (or regenerates) the insight for a session and returns it. The session must have finished.\n\nScope: `run`", "responses": { "201": { "description": "The generated insight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionInsight" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "run" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/messages": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listSessionMessages", "tags": [ "Sessions" ], "summary": "List messages", "description": "Poll the session's messages, cursor-paginated: pass the previous response's `end_cursor` as `after` (legacy spelling: `after_seq` / `next_seq`).\n\nScope: `sessions:read`", "responses": { "200": { "description": "A page of messages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "has_next_page": { "type": "boolean" }, "end_cursor": { "type": [ "string", "null" ] }, "next_seq": { "type": "integer", "description": "Legacy twin of end_cursor." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "in": "query", "name": "first", "schema": { "type": "integer", "default": 50 }, "description": "Page size (default 50, max 200)." }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Cursor from the previous page's `end_cursor`." }, { "in": "query", "name": "after_seq", "schema": { "type": "integer" }, "description": "Legacy spelling of `after`: return only messages with a higher sequence number." } ], "security": [ { "araApiKey": [ "sessions:read" ] } ] }, "post": { "operationId": "sendSessionMessage", "tags": [ "Sessions" ], "summary": "Send a message", "description": "Adds a follow-up instruction to a running session, like steering an engineer mid-task.\n\nScope: `run`", "responses": { "200": { "description": "Message accepted and delivered or queued for a continuation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSessionMessageResponse" } } } }, "400": { "description": "The message was empty, or a supplied `model` / `reasoning_effort` override was not valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "message_required", "invalid_model", "invalid_reasoning_effort" ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The session is read-only because it is a subagent, or is briefly unavailable while a newly attached repository becomes executable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "subagent_read_only", "session_transitioning" ] }, "message": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Follow-up instruction, at most 2 MiB when UTF-8 encoded." }, "model": { "type": "string", "description": "Optional model id from `GET /agent-auth/models` to retry this session on. A model override always starts a new continuation run, because a run's model is fixed at its first execution. Omit or use `auto` to keep the session's current model." }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh" ], "description": "Optional reasoning effort override applied to the continuation run." } }, "required": [ "message" ] }, "example": { "message": "Also bump the timeout to 30s while you're in there." } } } }, "security": [ { "araApiKey": [ "run" ] } ] } }, "/v3/organizations/{orgId}/sessions/{sessionId}/tags": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "sessionId", "description": "The session id.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listSessionTags", "tags": [ "Sessions" ], "summary": "List session tags", "responses": { "200": { "description": "The session's tags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "sessions:read" ] } ], "description": "Scope: `sessions:read`" }, "post": { "operationId": "appendSessionTags", "tags": [ "Sessions" ], "summary": "Append session tags", "description": "Adds tags to the session (set-union, deduped).\n\nScope: `run`", "responses": { "200": { "description": "Resulting tags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "tags" ] }, "example": { "tags": [ "release-blocker" ] } } } }, "security": [ { "araApiKey": [ "run" ] } ] }, "put": { "operationId": "replaceSessionTags", "tags": [ "Sessions" ], "summary": "Replace session tags", "responses": { "200": { "description": "Resulting tags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "tags" ] }, "example": { "tags": [ "ci", "release-blocker" ] } } } }, "security": [ { "araApiKey": [ "run" ] } ], "description": "Scope: `run`" }, "patch": { "operationId": "updateSessionTags", "tags": [ "Sessions" ], "summary": "Replace session tags", "responses": { "200": { "description": "Tags replaced.", "content": { "application/json": { "example": { "ok": true, "tags": [ "ci", "release-blocker" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "tags" ] }, "example": { "tags": [ "ci", "release-blocker" ] } } } }, "security": [ { "araApiKey": [ "run" ] } ], "description": "Scope: `run`" } }, "/v3/organizations/{orgId}/settings": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listSettings", "tags": [ "Settings" ], "summary": "List organization settings", "description": "Returns every namespaced setting as a map of namespace to its value object.\n\nScope: `org:read`", "responses": { "200": { "description": "Organization settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": { "type": "object" } } } } } } } }, "security": [ { "araApiKey": [ "org:read" ] } ] } }, "/v3/organizations/{orgId}/settings/{namespace}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "namespace", "description": "The settings namespace.", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSetting", "tags": [ "Settings" ], "summary": "Get a settings namespace", "description": "Returns the value object for a single settings namespace, or null if unset.\n\nScope: `org:read`", "responses": { "200": { "description": "The settings namespace value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "type": "string" }, "value": { "type": [ "object", "null" ] } } } } } } }, "security": [ { "araApiKey": [ "org:read" ] } ] }, "put": { "operationId": "updateSetting", "tags": [ "Settings" ], "summary": "Update a settings namespace", "description": "Replaces the value object for a single settings namespace. Only validated namespaces are writable; an unknown namespace returns a 400.\n\nScope: `org:write`", "responses": { "200": { "description": "The updated settings namespace value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "type": "string" }, "value": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "araApiKey": [ "org:write" ] } ] } }, "/v3/organizations/{orgId}/skills": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "listSkills", "tags": [ "Skills" ], "summary": "List skills", "description": "Returns all Workspace skill records, including authored skills and skills installed from packages or integrations.\n\nScope: `skills:read`", "responses": { "200": { "description": "Organization skills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "skills:read" ] } ] }, "post": { "operationId": "createSkill", "tags": [ "Skills" ], "summary": "Create a skill", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "description": "Skill instructions exceed the supported materialization size." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkill" }, "example": { "name": "Release checklist", "description": "Use when preparing a production release, deploying changes, or applying the team's release checklist.", "instructions": "Run the full test suite, update the changelog, then wait for a human approval before deploying.", "activation_keywords": [ "release", "deploy" ] } } } }, "security": [ { "araApiKey": [ "skills:write" ] } ], "description": "Scope: `skills:write`" } }, "/v3/organizations/{orgId}/skills/{skillId}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSkill", "tags": [ "Skills" ], "summary": "Retrieve a skill", "description": "Retrieves any Workspace skill record, whether authored or installed from a package or integration.\n\nScope: `skills:read`", "responses": { "200": { "description": "Skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "skills:read" ] } ] }, "put": { "operationId": "updateSkill", "tags": [ "Skills" ], "summary": "Update a skill", "description": "Partially updates an authored skill. Installed package and integration skills are read-only. Send only the fields you want to change.\n\nScope: `skills:write`", "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "Skill instructions exceed the supported materialization size." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkill" } } } }, "security": [ { "araApiKey": [ "skills:write" ] } ] }, "delete": { "operationId": "deleteSkill", "tags": [ "Skills" ], "summary": "Delete a skill", "description": "Deletes an authored skill. Installed package and integration skills are read-only.\n\nScope: `skills:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "skills:write" ] } ] } }, "/v3/self": { "get": { "operationId": "getSelf", "tags": [ "Account" ], "summary": "Verify credentials", "description": "Returns the principal behind the current key and the organization it can act on. Call this first to discover your `org_id`.\n\nAuth: any valid API key (no scope)", "responses": { "200": { "description": "The authenticated principal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Self" }, "example": { "principal_type": "service_user", "service_user_id": "key_3f9a", "service_user_name": "ci-bot", "org_id": "org_8c2d1e" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "araApiKey": [] } ] } } } }