> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Report a turn a computer runs with a message

> Records what the caller's machine bridge reports of a run of a message sent to the computer, and answers the run as it then stands. A run is the turn the bridge runs itself, resuming the session with the message as its prompt, when no terminal it can write to has the session open: the bridge reports the run in place of the message's delivery.

Use this tool when you need to:
- Ask to start the turn of a message the computer holds: Aether starts it, or queues it with the reason it cannot
- Report that the computer cannot run it now, and why
- Report that the run ended, and how

Examples:
- PUT /computers/{computerID}/terminal-chat-runs/{deliveryID} {"report": "start", "asked_at": "2026-11-08T06:00:00Z"}
- PUT /computers/{computerID}/terminal-chat-runs/{deliveryID} {"report": "queued", "reason": "not_signed_in"}
- PUT /computers/{computerID}/terminal-chat-runs/{deliveryID} {"report": "ended", "outcome": "finished", "ended_at": "2026-11-08T06:04:00Z"}

Hints:
- A start runs the turn only while the computer lets Aether start agents, runs fewer than its limit, and runs no other run of the chat; otherwise the answer is queued with agents_off, agent_limit or chat_busy, and the bridge asks again. Start the turn only on an answer of running: the message then reads relayed, and the session file delivers it. A start of a run already running answers it as it stands.
- The bridge queues a run itself, before it asks to start it, with open_in_terminal, not_signed_in or claude_not_found.
- Report ended once the run's process and every process it started have exited, with ended_at, when it ended on the computer's clock: the chat's turn ends as of then. A run that never started ends only failed, or turn_settings_refused when the bridge does not take the model or thinking level its message was sent with (turn_settings), which it never replaces with others; a retried end of the same outcome answers the run as it stands, and any other report of a run past it is refused with 409 terminal_chat_run_moved.
- The first report of a message the bridge took and has not reported (reportTerminalChatDelivery) moves it to wait on the computer, in the same step, as a message reported terminal_closed waits. A message with no run that the bridge reported otherwise, or that settled, is refused with 409 message_not_waiting. A message not sent to the caller's computer is refused with 404 not_found.
- Only the grant of the caller's coding agent's bridge calls it, the machine bridge on the computer: a session or an API key is refused with 403 credential_kind_not_admitted.
- The call presents the computer's own secret, which aether setup keeps on it, in the Aether-Computer-Secret header. A computer that has none is refused with 403 computer_needs_setup: update the aether CLI there and run aether setup. A call that presents no secret, or another, is refused with 403 computer_set_up_elsewhere.



## OpenAPI

````yaml api-reference/openapi.json PUT /computers/{computerID}/terminal-chat-runs/{deliveryID}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/terminal-chat-runs/{deliveryID}:
    put:
      tags:
        - computers
      summary: Report a turn a computer runs with a message
      description: >-
        Records what the caller's machine bridge reports of a run of a message
        sent to the computer, and answers the run as it then stands. A run is
        the turn the bridge runs itself, resuming the session with the message
        as its prompt, when no terminal it can write to has the session open:
        the bridge reports the run in place of the message's delivery.


        Use this tool when you need to:

        - Ask to start the turn of a message the computer holds: Aether starts
        it, or queues it with the reason it cannot

        - Report that the computer cannot run it now, and why

        - Report that the run ended, and how


        Examples:

        - PUT /computers/{computerID}/terminal-chat-runs/{deliveryID} {"report":
        "start", "asked_at": "2026-11-08T06:00:00Z"}

        - PUT /computers/{computerID}/terminal-chat-runs/{deliveryID} {"report":
        "queued", "reason": "not_signed_in"}

        - PUT /computers/{computerID}/terminal-chat-runs/{deliveryID} {"report":
        "ended", "outcome": "finished", "ended_at": "2026-11-08T06:04:00Z"}


        Hints:

        - A start runs the turn only while the computer lets Aether start
        agents, runs fewer than its limit, and runs no other run of the chat;
        otherwise the answer is queued with agents_off, agent_limit or
        chat_busy, and the bridge asks again. Start the turn only on an answer
        of running: the message then reads relayed, and the session file
        delivers it. A start of a run already running answers it as it stands.

        - The bridge queues a run itself, before it asks to start it, with
        open_in_terminal, not_signed_in or claude_not_found.

        - Report ended once the run's process and every process it started have
        exited, with ended_at, when it ended on the computer's clock: the chat's
        turn ends as of then. A run that never started ends only failed, or
        turn_settings_refused when the bridge does not take the model or
        thinking level its message was sent with (turn_settings), which it never
        replaces with others; a retried end of the same outcome answers the run
        as it stands, and any other report of a run past it is refused with 409
        terminal_chat_run_moved.

        - The first report of a message the bridge took and has not reported
        (reportTerminalChatDelivery) moves it to wait on the computer, in the
        same step, as a message reported terminal_closed waits. A message with
        no run that the bridge reported otherwise, or that settled, is refused
        with 409 message_not_waiting. A message not sent to the caller's
        computer is refused with 404 not_found.

        - Only the grant of the caller's coding agent's bridge calls it, the
        machine bridge on the computer: a session or an API key is refused with
        403 credential_kind_not_admitted.

        - The call presents the computer's own secret, which aether setup keeps
        on it, in the Aether-Computer-Secret header. A computer that has none is
        refused with 403 computer_needs_setup: update the aether CLI there and
        run aether setup. A call that presents no secret, or another, is refused
        with 403 computer_set_up_elsewhere.
      operationId: reportTerminalChatRun
      parameters:
        - in: path
          name: computerID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
        - in: path
          name: deliveryID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                asked_at:
                  description: >-
                    With start, and only with it: when the bridge asked, on the
                    computer's clock, which also stamps the session file's rows.
                    The run's prompt is a row stamped no earlier, so a person's
                    prompt of the same text written before is never taken for
                    it.
                  format: date-time
                  type: string
                ended_at:
                  description: >-
                    With ended, and only with it: when the run ended, on the
                    computer's clock, which also stamps the chat's statuses. The
                    run's end closes the chat's turn whose status began no
                    later, never a turn a terminal began after it.
                  format: date-time
                  type: string
                outcome:
                  description: >-
                    With ended, and only with it. A run that never started ends
                    only failed.
                  enum:
                    - finished
                    - stopped
                    - not_signed_in
                    - usage_limit
                    - failed
                    - interrupted
                    - fork_refused
                    - turn_settings_refused
                  type: string
                reason:
                  description: >-
                    With queued, and only with it: open_in_terminal while a
                    terminal the bridge cannot write to has the session open;
                    not_signed_in when Claude Code is not signed in on the
                    computer; claude_not_found when the bridge finds no claude.
                  enum:
                    - open_in_terminal
                    - not_signed_in
                    - claude_not_found
                  type: string
                report:
                  description: >-
                    start, with asked_at, to ask to run the turn: Aether starts
                    it, or queues it with the reason it cannot; queued, with
                    reason, when the computer cannot run it now; ended, with
                    outcome and ended_at, once the run's process and every
                    process it started have exited.
                  enum:
                    - start
                    - queued
                    - ended
                  type: string
              required:
                - report
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerTerminalChatRun'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ComputersErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Internal Server Error
components:
  schemas:
    ComputerTerminalChatRun:
      additionalProperties: false
      properties:
        delivery_id:
          description: The message the turn runs with.
          format: uuid
          type: string
        message:
          description: >-
            The message's text, kept exactly: at most 64 KiB of UTF-8, holding a
            character other than a space. A send refuses a slash command (text
            starting with /); a message stored before the send refused one may
            read as one.
          maxLength: 65536
          minLength: 1
          type: string
        run:
          $ref: '#/components/schemas/TerminalChatRun'
        session_id:
          description: Claude Code's own id of the session the run resumes.
          format: uuid
          type: string
        turn_settings:
          $ref: '#/components/schemas/TerminalChatTurnSettings'
      required:
        - delivery_id
        - session_id
        - message
        - turn_settings
        - run
      type: object
    ComputersErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - agent_starts_on_from_computer_only
            - agent_uses_own_sign_in
            - answer_on_its_way
            - app_identity_missing
            - attachments_unsupported
            - attribution_unavailable
            - bad_gateway
            - bad_request
            - base_branch_unusable
            - branch_exists
            - caller_inactive
            - chat_archived
            - chat_being_forked
            - chat_moved
            - chat_not_removable
            - chat_settings_fixed
            - chats_not_addable
            - checkout_not_archivable
            - cli_upgrade_required
            - client_outdated
            - computer_cli_outdated
            - computer_needs_fresh_sign_in
            - computer_needs_setup
            - computer_registered_to_another_person
            - computer_set_up_elsewhere
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_task_start_moved
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - credential_kind_not_admitted
            - credential_named_file
            - detached_head
            - download_unsupported
            - embeddings_unavailable
            - feature_unsupported
            - file_references_unsupported
            - fix_not_requested
            - fix_requests_unrecorded
            - forbidden
            - fork_branch_delete_unsupported
            - fork_forbidden
            - fork_in_progress
            - fork_unsupported
            - gateway_timeout
            - github_failed
            - github_identity_required
            - github_push_access_required
            - gone
            - handed_branch_protected
            - head_moved
            - html_render_nul_byte
            - html_render_too_large
            - idempotency_key_conflict
            - idempotency_key_reused
            - idle_compaction_not_pending
            - idle_compaction_skipped
            - inference_proxy_unavailable
            - insufficient_credits
            - insufficient_inference_balance
            - interaction_mode_unsupported
            - internal_error
            - invalid_request
            - last_queued_message
            - live_protocol_unsupported
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - message_not_waiting
            - method_not_allowed
            - mode_forbidden
            - name_follows_session
            - no_checkout_on_computer
            - no_checkpoint_yet
            - no_commit
            - no_dispatch_target
            - no_main_chat
            - no_origin
            - no_work_tree_folder
            - not_acceptable
            - not_found
            - not_implemented
            - onboarding_already_completed
            - onboarding_requirements_missing
            - open_in_terminal
            - org_id_required
            - org_role_insufficient
            - org_suspended
            - payment_required
            - pending_input_answered
            - permission_prompt_open
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_not_a_choice
            - project_required
            - prompt_decisions_refused
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - remote_changes_on_from_computer_only
            - repository_not_connected
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - service_unavailable
            - session_file_generation
            - session_file_hole
            - session_file_missing
            - session_file_range_differs
            - session_gone
            - session_not_started_by_aether
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - start_cancelled
            - stream_delivery_gap
            - stream_event_conflict
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_connection_disconnected
            - task_creator_deleted
            - task_has_no_branch
            - task_has_no_repository
            - task_ineligible
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_prompt_closed_otherwise
            - terminal_chat_prompt_differs
            - terminal_chat_prompt_not_answered
            - terminal_chat_removed
            - terminal_chat_run_moved
            - terminal_question
            - too_large
            - too_many_live_connections
            - too_many_waiting_messages
            - turn_running
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - user_suspended
            - validation_failed
            - work_tree_repository_differs
            - workspace_git_unavailable
            - workspace_gone
            - workspace_outdated
            - workspace_rejected
            - workspace_start_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    TerminalChatRun:
      description: >-
        A turn the computer runs with a message from Aether while no terminal
        has the chat's session open: Claude Code resumes the session there in
        print mode, with the person's own settings and sign-in. A terminal that
        opens the session meanwhile is told to wait.
      discriminator:
        mapping:
          ended: '#/components/schemas/TerminalChatRunEnded'
          queued: '#/components/schemas/TerminalChatRunQueued'
          running: '#/components/schemas/TerminalChatRunRunning'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/TerminalChatRunQueued'
        - $ref: '#/components/schemas/TerminalChatRunRunning'
        - $ref: '#/components/schemas/TerminalChatRunEnded'
    TerminalChatTurnSettings:
      additionalProperties: false
      description: >-
        The model and thinking level a turn Aether starts on a terminal chat
        runs with: what the computer's Claude Code takes for --model and
        --effort.
      properties:
        model:
          anyOf:
            - $ref: '#/components/schemas/TerminalChatModel'
            - type: 'null'
          description: >-
            The model the turn runs on; null for the computer's Claude Code's
            own, from its person's settings.
        reasoning_effort:
          anyOf:
            - $ref: '#/components/schemas/TerminalChatReasoningEffort'
            - type: 'null'
          description: >-
            The thinking level the turn runs at; null for the computer's Claude
            Code's own, from its person's settings.
      required:
        - model
        - reasoning_effort
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    TerminalChatRunEnded:
      additionalProperties: false
      description: The run ended. A chat shows an ended run for an hour.
      properties:
        delivery_id:
          description: 'The message the turn runs with: its delivery''s id.'
          format: uuid
          type: string
        ended_at:
          description: When the run ended.
          format: date-time
          type: string
        outcome:
          description: >-
            finished when the turn ran to its end; stopped when a stop from
            Aether, or archiving the chat, ended it, also while it was queued;
            not_signed_in when Claude Code said it is not signed in on the
            computer; usage_limit when Claude Code said the account reached its
            usage limit; failed when the turn did not run to its end, or never
            started; interrupted when its process ended while Aether on the
            computer was not watching it; fork_refused when the first run of a
            fork to the computer did not fork the source session into the
            chat's; turn_settings_refused when the aether CLI on the computer
            did not take the model or thinking level the message was sent with,
            before the run started.
          enum:
            - finished
            - stopped
            - not_signed_in
            - usage_limit
            - failed
            - interrupted
            - fork_refused
            - turn_settings_refused
          type: string
        started_at:
          description: >-
            When the computer started the turn; null for a run that was stopped,
            failed or refused its settings before it started.
          format: date-time
          type:
            - string
            - 'null'
        state:
          enum:
            - ended
          type: string
      required:
        - delivery_id
        - state
        - started_at
        - ended_at
        - outcome
      type: object
    TerminalChatRunQueued:
      additionalProperties: false
      description: >-
        The computer holds the message until it can run its turn: the message
        waits there for as long as the reason holds, until the chat is stopped
        (stopTaskChat) or archived, which ends the run stopped.
      properties:
        delivery_id:
          description: 'The message the turn runs with: its delivery''s id.'
          format: uuid
          type: string
        reason:
          description: >-
            agents_off when the computer does not let Aether start agents (only
            the computer turns that on: aether computer agents on, in a terminal
            there); agent_limit when it already runs as many agents as it lets
            Aether start at once; chat_busy while an earlier run of the chat
            runs; open_in_terminal while a terminal Aether cannot write to has
            the session open; not_signed_in when Claude Code is not signed in on
            the computer (signing in is its person's own job); claude_not_found
            when the computer has no claude Aether can find. The computer asks
            again, so the run starts once its reason is gone.
          enum:
            - agents_off
            - agent_limit
            - chat_busy
            - open_in_terminal
            - not_signed_in
            - claude_not_found
          type: string
        since:
          description: When the computer first held the message back.
          format: date-time
          type: string
        state:
          enum:
            - queued
          type: string
      required:
        - delivery_id
        - state
        - reason
        - since
      type: object
    TerminalChatRunRunning:
      additionalProperties: false
      description: >-
        The computer runs the turn: Claude Code resumed the session there, with
        the message as its prompt. A stop ends it at once.
      properties:
        delivery_id:
          description: 'The message the turn runs with: its delivery''s id.'
          format: uuid
          type: string
        started_at:
          description: When the computer started the turn.
          format: date-time
          type: string
        state:
          enum:
            - running
          type: string
      required:
        - delivery_id
        - state
        - started_at
      type: object
    TerminalChatModel:
      description: >-
        A model family Claude Code's --model takes by its alias: the newest
        model of the family the computer's Claude Code serves.
      enum:
        - fable
        - opus
        - sonnet
        - haiku
      type: string
    TerminalChatReasoningEffort:
      description: A thinking level Claude Code's --effort takes.
      enum:
        - low
        - medium
        - high
        - xhigh
        - max
      type: string
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.