{ "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 that activate 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, plugins:read, secrets:read, secrets:write, sessions:read, knowledge:read, repos:read, repos:write, reviews:read, reviews:write, analytics:read, org:read, org:write, attachments:read, attachments:write, plugins:write, guardrails:read, guardrails:write." } }, "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." }, "ConnectAzureOpenAi": { "type": "object", "properties": { "endpoint_url": { "type": "string", "description": "The Azure OpenAI / AI Foundry resource endpoint, e.g. `https://YOUR_RESOURCE_NAME.openai.azure.com`." }, "deployment_name": { "type": "string", "description": "The deployment name YOU gave this model in Azure AI Foundry — not the underlying model name." }, "api_key": { "type": "string", "description": "One of the resource's two API keys (Keys and Endpoint page). Stored encrypted, never returned. Omit when connecting via Entra ID instead." }, "tenant_id": { "type": "string", "description": "Azure AD tenant (directory) ID. Send with client_id + client_secret instead of api_key to connect via Entra ID." }, "client_id": { "type": "string", "description": "The Entra ID app registration's client (application) ID." }, "client_secret": { "type": "string", "description": "The Entra ID app registration's client secret value. Stored encrypted, never returned." } }, "required": [ "endpoint_url", "deployment_name", "api_key" ] }, "ConnectByokProvider": { "type": "object", "properties": { "key": { "type": "string", "description": "The provider's own API key. Stored encrypted, never returned." } }, "required": [ "key" ] }, "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" ] }, "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." }, "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." }, "tags": { "type": "array", "items": { "type": "string" } }, "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." }, "create_as_user_id": { "type": "string", "description": "Attribute the session to another member (service users only)." }, "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", "repo" ] }, "CreateSkill": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "string" }, "activation_keywords": { "type": "array", "items": { "type": "string" } }, "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`." }, "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" } } }, "Organization": { "type": "object", "properties": { "org_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "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" }, "role": { "type": "string", "enum": [ "pro", "regular" ] }, "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 new session created to continue a completed run. Clients should switch their event and message polling to this id.", "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": { "type": [ "string", "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" ] }, "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" }, "parent_session_id": { "description": "Always null (no session hierarchy).", "type": [ "string", "null" ] }, "child_session_ids": { "type": "array", "items": { "type": "string" }, "description": "Always empty (no session hierarchy)." }, "is_advanced": { "type": "boolean", "description": "Always false." } } }, "SessionEvent": { "type": "object", "properties": { "id": { "type": "string" }, "seq": { "type": "integer", "description": "Monotonic event sequence number." }, "type": { "type": "string", "description": "Event kind such as assistant, reasoning, tool_use, tool_result, or status." }, "text": { "type": [ "string", "null" ] }, "data": { "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" }, "instructions": { "type": "string" }, "activation_keywords": { "type": "array", "items": { "type": "string" } }, "is_enabled": { "type": "boolean" }, "author": { "type": "string" }, "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" }, "instructions": { "type": "string" }, "activation_keywords": { "type": "array", "items": { "type": "string" } }, "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/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/azure-openai/connect": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "post": { "operationId": "connectAzureOpenAi", "tags": [ "Agent Auth" ], "summary": "Connect an Azure OpenAI deployment (temporarily unavailable)", "deprecated": true, "responses": { "200": { "description": "Legacy compatibility response (not currently returned)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "410": { "description": "Additional models are temporarily unavailable." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectAzureOpenAi" } } } }, "security": [ { "araApiKey": [ "agent_auth:write" ] } ], "description": "Scope: `agent_auth:write`" } }, "/v3/organizations/{orgId}/agent-auth/byok/usage": { "parameters": [ { "$ref": "#/components/parameters/orgId" } ], "get": { "operationId": "getByokUsage", "tags": [ "Agent Auth" ], "summary": "Get per-user BYOK spend (temporarily unavailable)", "deprecated": true, "responses": { "200": { "description": "Legacy BYOK usage totals (not currently returned)." }, "410": { "description": "Additional models are temporarily unavailable." }, "503": { "description": "BYOK provisioning is not configured on this deployment." } }, "security": [ { "araApiKey": [ "agent_auth:read" ] } ], "description": "Scope: `agent_auth:read`" } }, "/v3/organizations/{orgId}/agent-auth/byok/{provider}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "provider", "description": "Legacy agent-auth provider id. Provider connection operations are temporarily unavailable.", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "disconnectByokProvider", "tags": [ "Agent Auth" ], "summary": "Disconnect a BYOK vendor key (temporarily unavailable)", "deprecated": true, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "410": { "description": "Additional models are temporarily unavailable." } }, "security": [ { "araApiKey": [ "agent_auth:write" ] } ], "description": "Scope: `agent_auth:write`" } }, "/v3/organizations/{orgId}/agent-auth/byok/{provider}/connect": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "provider", "description": "Legacy agent-auth provider id. Provider connection operations are temporarily unavailable.", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "connectByokProvider", "tags": [ "Agent Auth" ], "summary": "Connect a BYOK vendor key (temporarily unavailable)", "deprecated": true, "responses": { "200": { "description": "Legacy compatibility response (not currently returned)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "410": { "description": "Additional models are temporarily unavailable." }, "503": { "description": "BYOK provisioning is not configured on this deployment." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectByokProvider" } } } }, "security": [ { "araApiKey": [ "agent_auth:write" ] } ], "description": "Scope: `agent_auth: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}/agent-auth/{provider}": { "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "name": "provider", "description": "Legacy agent-auth provider id. Provider connection operations are temporarily unavailable.", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "disconnectAgentAuthProvider", "tags": [ "Agent Auth" ], "summary": "Disconnect a connected provider (temporarily unavailable)", "deprecated": true, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "410": { "description": "Additional models are temporarily unavailable." } }, "security": [ { "araApiKey": [ "agent_auth:write" ] } ], "description": "Scope: `agent_auth:write`" } }, "/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: `plugins: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": [ "plugins: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: `plugins: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": [ "plugins: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: `plugins:read`", "responses": { "200": { "description": "The MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "plugins: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: `plugins: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": [ "plugins:write" ] } ] }, "delete": { "operationId": "deleteMcpServer", "tags": [ "MCP Servers" ], "summary": "Delete an MCP server", "description": "Removes an org-level MCP server.\n\nScope: `plugins:write`", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "plugins: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}/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", "tags": [ "Roles" ], "summary": "List role assignments", "description": "Returns the role assigned to each member.\n\nScope: `org:read`", "responses": { "200": { "description": "Role assignments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } }, "total": { "type": "integer" } } } } } } }, "security": [ { "araApiKey": [ "org:read" ] } ] }, "put": { "operationId": "setRoleAssignment", "tags": [ "Roles" ], "summary": "Set a role assignment", "description": "Assigns a role to a member.\n\nScope: `org:write`", "responses": { "200": { "description": "Role assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "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 role assignment in this organization.\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", "tags": [ "Roles" ], "summary": "Get a member's role", "responses": { "200": { "description": "The role assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "org:read" ] } ], "description": "Scope: `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/{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.\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 scratch session. Discovery from scratch is advisory; repository work starts in another session created with the exact target because bindings are immutable. 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", "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "sessions:read" ] } ], "description": "Scope: `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" } }, "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.\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": "Subagent sessions are read-only and must be continued from their parent session.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "subagent_read_only" ] }, "message": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "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", "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" ] } ], "description": "Scope: `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": "The team's release process.", "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", "responses": { "200": { "description": "Skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "skills:read" ] } ], "description": "Scope: `skills:read`" }, "put": { "operationId": "updateSkill", "tags": [ "Skills" ], "summary": "Update a skill", "description": "Partial update. 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", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "araApiKey": [ "skills:write" ] } ], "description": "Scope: `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": [] } ] } } } }