> ## Documentation Index > Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Pin an immutable action and schedule revision > expectedRevision is zero for initial configuration. Edits affect future occurrences only. Tool calls and jobs create no reasoning Session. The automation may have no trigger or one schedule trigger not bound to a Session; other trigger configurations are refused. The response returns the pinned revision without its captured authorization principal or admission counters. Scope: `automations:write` ## OpenAPI ````yaml /openapi.json put /v3/organizations/{orgId}/automations/{automationId}/action openapi: 3.1.0 info: title: Reason API version: 3.0.0 description: >- The Reason HTTP API. Drive cloud software-engineering agents: open sessions against your repositories, stream their work, and manage the secrets, skills, and automations they run with. Authenticate with a Reason API key sent as a bearer token. New keys use `reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to an organization; resolve your `org_id` once with `GET /v3/self`. servers: - url: https://api.reasonmachines.com security: - reasonApiKey: [] tags: - name: Account description: Verify a key and resolve the organization it belongs to. - name: Reasons description: >- Start here. A Reason is the long-running agent a person keeps: their main Reason and named ones, each with its own instructions, default model and repositories, conversation, Loops and Sessions. Give a Reason work by messaging it (sendReasonMessage) and read its replies with listReasonMessages. - name: Loops description: >- Standing work a Reason does, woken by a schedule or an event: a webhook, a GitHub event or a Slack message. Each wake opens or continues a Session of the Reason; webhook events that share a correlation key continue one Session. - name: Memory description: >- What Reasons remember across Sessions. Each Session starts by reading MEMORY.md (a short index) and the list of topic notes, and reads a note when its topic comes up. `personal` memory belongs to one person (the API key's owner) and only their Sessions read it; `team` memory belongs to the Workspace and every member's Sessions read it. memory:read lists, reads and searches; memory:write writes and deletes, in team memory only for a Workspace owner or admin. - name: Sessions description: >- A Session is one run of work inside a Reason: every Reason message and Loop wake runs in one, and createSession starts one directly for a single unattended task with a pass/fail outcome. Its transcript, events, result and pull request are read here. - name: Skills description: >- Reusable instruction bundles Reason selects semantically from their descriptions for matching agent tasks. - name: Secrets description: >- Encrypted credentials injected into the agent's sandbox. Write-only: values can be set but never read back. - name: Attachments description: >- Files uploaded to the organization and shared with sessions, downloaded via short-lived signed URLs. - 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: Machines description: >- Named Workspace queues served by headless workers. Sessions target a Machine by name and wait for a free worker; more workers serve more Sessions concurrently. - name: Devices description: >- Owned Mac and headless Device identity, bounded enrollment and root grants. - name: Cloud Access description: >- Keyless cloud sign-in for sessions: Reason's OIDC issuer facts and the AWS, Google Cloud and Azure connections a workspace trusts, including which run triggers each one signs in. - name: MCP Servers description: >- Org-level Model Context Protocol servers exposed to the agent. Secret values are write-only. - name: Change Request Reviews description: >- Automated senior-engineer reviews posted on pull requests and merge requests. - 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: Roles description: Role assignments that govern what each member can do. - name: Settings description: 'Organization configuration: namespaced settings and the run tag policy.' - name: Provider credentials description: >- Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials for model providers. Secret values are write-only. - name: Feedback description: Report problems with the API or these docs to the Reason team. - name: Projects description: >- Deprecated: a project is a Reason with the same id. Use the Reasons operations; these remain for existing clients. - name: Automations description: >- The older form of Loops. Prefer the Loops under a Reason (listReasonLoops, createReasonLoop), which take every wake: schedule, webhook, GitHub, Slack. Use these for what Loops do not carry yet: a run's MCP and app tools, and automations not filed under a Reason. paths: /v3/organizations/{orgId}/automations/{automationId}/action: parameters: - $ref: '#/components/parameters/orgId' - name: automationId description: >- The automation id, returned as `id` by `listAutomations` and `createAutomation`. in: path required: true schema: type: string put: tags: - Automations summary: Pin an immutable action and schedule revision description: >- expectedRevision is zero for initial configuration. Edits affect future occurrences only. Tool calls and jobs create no reasoning Session. The automation may have no trigger or one schedule trigger not bound to a Session; other trigger configurations are refused. The response returns the pinned revision without its captured authorization principal or admission counters. Scope: `automations:write` operationId: configureAutomationAction requestBody: required: true content: application/json: schema: type: object properties: expectedRevision: type: integer minimum: 0 action: oneOf: - type: object properties: kind: type: string const: tool_call connectionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ tool: type: string minLength: 1 maxLength: 256 input: type: object connectionRevision: type: string minLength: 1 maxLength: 256 schemaDigest: type: string pattern: ^[a-f0-9]{64}$ required: - kind - connectionId - tool - input - schemaDigest additionalProperties: false - type: object properties: kind: type: string const: job job: type: object properties: device_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ root_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ mode: type: string enum: - confined - host operation: oneOf: - type: object properties: kind: type: string const: command command: type: string minLength: 1 maxLength: 65536 cwd: default: . type: string minLength: 1 maxLength: 4096 timeout_ms: default: 15000 type: integer minimum: 100 maximum: 60000 required: - kind - command additionalProperties: false - type: object properties: kind: type: string const: files.read path: type: string minLength: 1 maxLength: 4096 offset: default: 0 type: integer minimum: 0 max_bytes: default: 65536 type: integer minimum: 1 maximum: 131072 required: - kind - path additionalProperties: false - type: object properties: kind: type: string const: files.write path: type: string minLength: 1 maxLength: 4096 content: type: string maxLength: 131072 mode: default: create type: string enum: - create - overwrite - append required: - kind - path - content additionalProperties: false - type: object properties: kind: type: string const: terminal.open cwd: default: . type: string minLength: 1 maxLength: 4096 columns: default: 80 type: integer minimum: 1 maximum: 500 rows: default: 24 type: integer minimum: 1 maximum: 300 required: - kind additionalProperties: false - type: object properties: kind: type: string const: terminal.input terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sequence: type: integer minimum: 0 data: type: string maxLength: 8192 required: - kind - terminal_id - sequence - data additionalProperties: false - type: object properties: kind: type: string const: terminal.output terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ after: default: 0 type: integer minimum: 0 required: - kind - terminal_id additionalProperties: false - type: object properties: kind: type: string const: terminal.resize terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sequence: type: integer minimum: 0 columns: type: integer minimum: 1 maximum: 500 rows: type: integer minimum: 1 maximum: 300 required: - kind - terminal_id - sequence - columns - rows additionalProperties: false - type: object properties: kind: type: string const: artifacts.upload_checkpoint artifact_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ source_path: type: string minLength: 1 maxLength: 4096 required: - kind - artifact_id - source_path additionalProperties: false - type: object properties: kind: type: string const: artifacts.export path: type: string minLength: 1 maxLength: 4096 max_bytes: default: 131072 type: integer minimum: 1 maximum: 131072 required: - kind - path additionalProperties: false - type: object properties: kind: type: string const: terminal.close terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - terminal_id additionalProperties: false - type: object properties: kind: type: string const: browser.click browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ selector: type: string minLength: 1 maxLength: 1024 required: - kind - browser_id - selector additionalProperties: false - type: object properties: kind: type: string const: browser.fill browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ selector: type: string minLength: 1 maxLength: 1024 value: type: string maxLength: 8192 required: - kind - browser_id - selector - value additionalProperties: false - type: object properties: kind: type: string const: browser.press browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ selector: type: string minLength: 1 maxLength: 1024 key: type: string minLength: 1 maxLength: 128 required: - kind - browser_id - selector - key additionalProperties: false - type: object properties: kind: type: string const: computer.list required: - kind additionalProperties: false - type: object properties: kind: type: string const: computer.snapshot app: type: string minLength: 1 maxLength: 256 required: - kind - app additionalProperties: false - type: object properties: kind: type: string const: computer.act snapshot_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ action: oneOf: - type: object properties: kind: type: string const: click_pixel x: type: integer minimum: 0 maximum: 8192 'y': type: integer minimum: 0 maximum: 8192 required: - kind - x - 'y' additionalProperties: false - type: object properties: kind: type: string const: click_element element_index: type: integer minimum: 0 maximum: 9999 role: type: string minLength: 1 maxLength: 128 required: - kind - element_index - role additionalProperties: false - type: object properties: kind: type: string const: type_text text: type: string maxLength: 8192 required: - kind - text additionalProperties: false - type: object properties: kind: type: string const: key_press key: type: string minLength: 1 maxLength: 128 required: - kind - key additionalProperties: false required: - kind - snapshot_id - action additionalProperties: false - type: object properties: kind: type: string const: browser.navigate browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ url: type: string maxLength: 4096 format: uri required: - kind - browser_id - url additionalProperties: false - type: object properties: kind: type: string const: browser.open allowed_domains: default: [] maxItems: 64 type: array items: type: string minLength: 1 maxLength: 253 required: - kind additionalProperties: false - type: object properties: kind: type: string const: browser.snapshot browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - browser_id additionalProperties: false - type: object properties: kind: type: string const: browser.screenshot browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - browser_id additionalProperties: false - type: object properties: kind: type: string const: browser.close browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - browser_id additionalProperties: false - type: object properties: kind: type: string const: preview.open job_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ port: type: integer minimum: 1 maximum: 65535 required: - kind - job_id - port additionalProperties: false - type: object properties: kind: type: string const: preview.request preview_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ path: type: string minLength: 1 maxLength: 4096 pattern: ^\/(?!\/) required: - kind - preview_id - path additionalProperties: false - type: object properties: kind: type: string const: preview.close preview_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - preview_id additionalProperties: false delegation: type: object properties: operations: minItems: 1 maxItems: 32 type: array items: type: object properties: operation_id: type: string minLength: 1 maxLength: 160 path: type: string minLength: 1 maxLength: 2048 query: default: {} type: object additionalProperties: type: string body: {} resource: oneOf: - type: object properties: kind: type: string const: own_invocations required: - kind additionalProperties: false - type: object properties: kind: type: string const: own_job required: - kind additionalProperties: false - type: object properties: kind: type: string const: tool connection_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ tool_name: type: string minLength: 1 maxLength: 256 schema_digest: type: string pattern: ^[a-f0-9]{64}$ connection_revision: type: string minLength: 1 maxLength: 256 required: - kind - connection_id - tool_name - schema_digest - connection_revision additionalProperties: false - type: object properties: kind: type: string const: memory scope: type: string enum: - personal - team path: type: string minLength: 1 maxLength: 512 required: - kind - scope additionalProperties: false - type: object properties: kind: type: string const: repository repository: type: string pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$ required: - kind - repository additionalProperties: false max_calls: default: 1 type: integer minimum: 1 maximum: 1000 required: - operation_id - path additionalProperties: false required: - operations additionalProperties: false expected_root_grant_revision: type: integer exclusiveMinimum: 0 expected_direct_access_revision: type: integer minimum: 0 expected_root_path_fingerprint: type: string minLength: 1 maxLength: 256 context_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - device_id - root_id - mode - operation additionalProperties: false required: - kind - job additionalProperties: false - type: object properties: kind: type: string const: agent_task prompt: type: string minLength: 1 maxLength: 100000 sessionTarget: oneOf: - type: string const: new - type: object properties: sessionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - sessionId additionalProperties: false required: - kind - prompt - sessionTarget additionalProperties: false schedule: oneOf: - type: object properties: kind: type: string const: every everySeconds: type: integer minimum: 60 maximum: 31536000 timezone: type: string minLength: 1 maxLength: 100 required: - kind - everySeconds - timezone additionalProperties: false - type: object properties: kind: type: string const: cron expression: type: string minLength: 1 maxLength: 256 timezone: type: string minLength: 1 maxLength: 100 required: - kind - expression - timezone additionalProperties: false - type: object properties: kind: type: string const: at at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ timezone: type: string minLength: 1 maxLength: 100 required: - kind - at - timezone additionalProperties: false limits: type: object properties: maxAttempts: type: integer minimum: 1 maximum: 5 retryDelaySeconds: type: integer minimum: 60 maximum: 3600 startDeadlineSeconds: type: integer minimum: 60 maximum: 86400 timeoutSeconds: type: integer minimum: 1 maximum: 86400 maxOccurrences: type: integer minimum: 1 maximum: 10000 maxCalls: type: integer minimum: 1 maximum: 50000 overlap: type: string enum: - skip - allow maxConcurrent: type: integer minimum: 1 maximum: 10 missedSlots: type: string enum: - skip - coalesce required: - maxAttempts - retryDelaySeconds - startDeadlineSeconds - timeoutSeconds - maxOccurrences - maxCalls - overlap - maxConcurrent - missedSlots additionalProperties: false required: - expectedRevision - action - schedule - limits additionalProperties: false responses: '200': description: New pinned revision. content: application/json: schema: $ref: '#/components/schemas/DirectAutomationRevision' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: The current revision changed; read it and retry. '429': $ref: '#/components/responses/RateLimited' security: - reasonApiKey: - automations:write components: parameters: orgId: name: orgId in: path required: true description: Organization id or slug. Resolve it with `GET /v3/self`. schema: type: string schemas: DirectAutomationRevision: type: object properties: action: oneOf: - type: object properties: kind: type: string const: tool_call connectionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ tool: type: string minLength: 1 maxLength: 256 input: type: object connectionRevision: type: string minLength: 1 maxLength: 256 schemaDigest: type: string pattern: ^[a-f0-9]{64}$ required: - kind - connectionId - tool - input - schemaDigest additionalProperties: false - type: object properties: kind: type: string const: job job: type: object properties: device_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ root_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ mode: type: string enum: - confined - host operation: oneOf: - type: object properties: kind: type: string const: command command: type: string minLength: 1 maxLength: 65536 cwd: default: . type: string minLength: 1 maxLength: 4096 timeout_ms: default: 15000 type: integer minimum: 100 maximum: 60000 required: - kind - command additionalProperties: false - type: object properties: kind: type: string const: files.read path: type: string minLength: 1 maxLength: 4096 offset: default: 0 type: integer minimum: 0 max_bytes: default: 65536 type: integer minimum: 1 maximum: 131072 required: - kind - path additionalProperties: false - type: object properties: kind: type: string const: files.write path: type: string minLength: 1 maxLength: 4096 content: type: string maxLength: 131072 mode: default: create type: string enum: - create - overwrite - append required: - kind - path - content additionalProperties: false - type: object properties: kind: type: string const: terminal.open cwd: default: . type: string minLength: 1 maxLength: 4096 columns: default: 80 type: integer minimum: 1 maximum: 500 rows: default: 24 type: integer minimum: 1 maximum: 300 required: - kind additionalProperties: false - type: object properties: kind: type: string const: terminal.input terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sequence: type: integer minimum: 0 data: type: string maxLength: 8192 required: - kind - terminal_id - sequence - data additionalProperties: false - type: object properties: kind: type: string const: terminal.output terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ after: default: 0 type: integer minimum: 0 required: - kind - terminal_id additionalProperties: false - type: object properties: kind: type: string const: terminal.resize terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sequence: type: integer minimum: 0 columns: type: integer minimum: 1 maximum: 500 rows: type: integer minimum: 1 maximum: 300 required: - kind - terminal_id - sequence - columns - rows additionalProperties: false - type: object properties: kind: type: string const: artifacts.upload_checkpoint artifact_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ source_path: type: string minLength: 1 maxLength: 4096 required: - kind - artifact_id - source_path additionalProperties: false - type: object properties: kind: type: string const: artifacts.export path: type: string minLength: 1 maxLength: 4096 max_bytes: default: 131072 type: integer minimum: 1 maximum: 131072 required: - kind - path additionalProperties: false - type: object properties: kind: type: string const: terminal.close terminal_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - terminal_id additionalProperties: false - type: object properties: kind: type: string const: browser.click browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ selector: type: string minLength: 1 maxLength: 1024 required: - kind - browser_id - selector additionalProperties: false - type: object properties: kind: type: string const: browser.fill browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ selector: type: string minLength: 1 maxLength: 1024 value: type: string maxLength: 8192 required: - kind - browser_id - selector - value additionalProperties: false - type: object properties: kind: type: string const: browser.press browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ selector: type: string minLength: 1 maxLength: 1024 key: type: string minLength: 1 maxLength: 128 required: - kind - browser_id - selector - key additionalProperties: false - type: object properties: kind: type: string const: computer.list required: - kind additionalProperties: false - type: object properties: kind: type: string const: computer.snapshot app: type: string minLength: 1 maxLength: 256 required: - kind - app additionalProperties: false - type: object properties: kind: type: string const: computer.act snapshot_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ action: oneOf: - type: object properties: kind: type: string const: click_pixel x: type: integer minimum: 0 maximum: 8192 'y': type: integer minimum: 0 maximum: 8192 required: - kind - x - 'y' additionalProperties: false - type: object properties: kind: type: string const: click_element element_index: type: integer minimum: 0 maximum: 9999 role: type: string minLength: 1 maxLength: 128 required: - kind - element_index - role additionalProperties: false - type: object properties: kind: type: string const: type_text text: type: string maxLength: 8192 required: - kind - text additionalProperties: false - type: object properties: kind: type: string const: key_press key: type: string minLength: 1 maxLength: 128 required: - kind - key additionalProperties: false required: - kind - snapshot_id - action additionalProperties: false - type: object properties: kind: type: string const: browser.navigate browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ url: type: string maxLength: 4096 format: uri required: - kind - browser_id - url additionalProperties: false - type: object properties: kind: type: string const: browser.open allowed_domains: default: [] maxItems: 64 type: array items: type: string minLength: 1 maxLength: 253 required: - kind additionalProperties: false - type: object properties: kind: type: string const: browser.snapshot browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - browser_id additionalProperties: false - type: object properties: kind: type: string const: browser.screenshot browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - browser_id additionalProperties: false - type: object properties: kind: type: string const: browser.close browser_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - browser_id additionalProperties: false - type: object properties: kind: type: string const: preview.open job_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ port: type: integer minimum: 1 maximum: 65535 required: - kind - job_id - port additionalProperties: false - type: object properties: kind: type: string const: preview.request preview_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ path: type: string minLength: 1 maxLength: 4096 pattern: ^\/(?!\/) required: - kind - preview_id - path additionalProperties: false - type: object properties: kind: type: string const: preview.close preview_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - preview_id additionalProperties: false delegation: type: object properties: operations: minItems: 1 maxItems: 32 type: array items: type: object properties: operation_id: type: string minLength: 1 maxLength: 160 path: type: string minLength: 1 maxLength: 2048 query: default: {} type: object additionalProperties: type: string body: {} resource: oneOf: - type: object properties: kind: type: string const: own_invocations required: - kind additionalProperties: false - type: object properties: kind: type: string const: own_job required: - kind additionalProperties: false - type: object properties: kind: type: string const: tool connection_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ tool_name: type: string minLength: 1 maxLength: 256 schema_digest: type: string pattern: ^[a-f0-9]{64}$ connection_revision: type: string minLength: 1 maxLength: 256 required: - kind - connection_id - tool_name - schema_digest - connection_revision additionalProperties: false - type: object properties: kind: type: string const: memory scope: type: string enum: - personal - team path: type: string minLength: 1 maxLength: 512 required: - kind - scope additionalProperties: false - type: object properties: kind: type: string const: repository repository: type: string pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$ required: - kind - repository additionalProperties: false max_calls: default: 1 type: integer minimum: 1 maximum: 1000 required: - operation_id - path additionalProperties: false required: - operations additionalProperties: false expected_root_grant_revision: type: integer exclusiveMinimum: 0 expected_direct_access_revision: type: integer minimum: 0 expected_root_path_fingerprint: type: string minLength: 1 maxLength: 256 context_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - device_id - root_id - mode - operation additionalProperties: false required: - kind - job additionalProperties: false - type: object properties: kind: type: string const: agent_task prompt: type: string minLength: 1 maxLength: 100000 sessionTarget: oneOf: - type: string const: new - type: object properties: sessionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - sessionId additionalProperties: false required: - kind - prompt - sessionTarget additionalProperties: false schedule: oneOf: - type: object properties: kind: type: string const: every everySeconds: type: integer minimum: 60 maximum: 31536000 timezone: type: string minLength: 1 maxLength: 100 required: - kind - everySeconds - timezone additionalProperties: false - type: object properties: kind: type: string const: cron expression: type: string minLength: 1 maxLength: 256 timezone: type: string minLength: 1 maxLength: 100 required: - kind - expression - timezone additionalProperties: false - type: object properties: kind: type: string const: at at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ timezone: type: string minLength: 1 maxLength: 100 required: - kind - at - timezone additionalProperties: false limits: type: object properties: maxAttempts: type: integer minimum: 1 maximum: 5 retryDelaySeconds: type: integer minimum: 60 maximum: 3600 startDeadlineSeconds: type: integer minimum: 60 maximum: 86400 timeoutSeconds: type: integer minimum: 1 maximum: 86400 maxOccurrences: type: integer minimum: 1 maximum: 10000 maxCalls: type: integer minimum: 1 maximum: 50000 overlap: type: string enum: - skip - allow maxConcurrent: type: integer minimum: 1 maximum: 10 missedSlots: type: string enum: - skip - coalesce required: - maxAttempts - retryDelaySeconds - startDeadlineSeconds - timeoutSeconds - maxOccurrences - maxCalls - overlap - maxConcurrent - missedSlots additionalProperties: false organizationId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ automationId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ triggerId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ ownerId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ revision: type: integer exclusiveMinimum: 0 required: - action - schedule - limits - organizationId - automationId - triggerId - ownerId - revision description: >- The pinned action, schedule and limits for one revision, returned only to the creator. The captured authorization principal is excluded. Error: type: object properties: error: oneOf: - type: string - type: object required: - type - message properties: type: type: string message: type: string request_id: type: - string - 'null' message: type: string required_scope: type: string description: >- The capability required when the request was denied for a missing scope. responses: Unauthorized: description: Missing, invalid, or expired key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_bearer message: Authorization required Forbidden: description: The key lacks the required scope or role. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_scope required_scope: sessions:read RateLimited: description: >- Too many requests. Retry after the number of seconds in the `Retry-After` response header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 required: true content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limited message: This API key exceeded its request-rate limit securitySchemes: reasonApiKey: type: http scheme: bearer bearerFormat: 'reason_ (legacy: ara_)' description: >- Your Reason API key from Settings › API keys. New keys use `reason_`; legacy `ara_` keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. network:read and network:write are opt-in, excluded from default keys. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.