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

# Ship a range of a terminal chat's session file

> Stores a range of one file of a terminal chat's session artifact, by byte offset, and answers what Aether then holds of the file and whether the chat runs a turn then. The machine bridge ships each file's new lines as they are written.

Use this tool when you need to:
- Ship the lines a Claude Code session wrote to its session file, or to a sub-agent's file beside it
- Replace a file that was rotated, truncated or rewritten under the bridge's cursor

Examples:
- PUT /computers/{computerID}/terminal-chats/{sessionID}/session-files/session {"generation": 1, "offset": 0, "bytes": "eyJ0eXBlIjoidXNlciJ9Cg=="}

Hints:
- bytes are 1 byte to 4 MiB, base64. A range is idempotent by offset: the part Aether already holds must match the stored bytes and is stored once, so a resent range is harmless.
- A range that starts past the end of what Aether holds is refused with 409 session_file_hole; one of another generation with 409 session_file_generation; one whose bytes differ from the stored bytes at the same offsets with 409 session_file_range_differs. Read the file with getTerminalChatSessionFile and ship from what Aether holds.
- A range of the generation after the current one, from offset 0, replaces the file: the replaced marker, from which the chat's record is read anew.
- A range of the session file names the chat by the session's first prompt and records the times its lines carry.
- turn_running is whether the chat runs a turn once the range is taken in, read with it: a range whose lines end a turn no hook reported (Escape, a prompt a hook blocked) answers false, and so does the same range sent again after its answer was lost, until a later turn begins.
- A session the computer holds no chat of for the caller (ensureTerminalChat creates it), or a computer that is not theirs, 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-chats/{sessionID}/session-files/{file}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/terminal-chats/{sessionID}/session-files/{file}:
    put:
      tags:
        - computers
      summary: Ship a range of a terminal chat's session file
      description: >-
        Stores a range of one file of a terminal chat's session artifact, by
        byte offset, and answers what Aether then holds of the file and whether
        the chat runs a turn then. The machine bridge ships each file's new
        lines as they are written.


        Use this tool when you need to:

        - Ship the lines a Claude Code session wrote to its session file, or to
        a sub-agent's file beside it

        - Replace a file that was rotated, truncated or rewritten under the
        bridge's cursor


        Examples:

        - PUT
        /computers/{computerID}/terminal-chats/{sessionID}/session-files/session
        {"generation": 1, "offset": 0, "bytes": "eyJ0eXBlIjoidXNlciJ9Cg=="}


        Hints:

        - bytes are 1 byte to 4 MiB, base64. A range is idempotent by offset:
        the part Aether already holds must match the stored bytes and is stored
        once, so a resent range is harmless.

        - A range that starts past the end of what Aether holds is refused with
        409 session_file_hole; one of another generation with 409
        session_file_generation; one whose bytes differ from the stored bytes at
        the same offsets with 409 session_file_range_differs. Read the file with
        getTerminalChatSessionFile and ship from what Aether holds.

        - A range of the generation after the current one, from offset 0,
        replaces the file: the replaced marker, from which the chat's record is
        read anew.

        - A range of the session file names the chat by the session's first
        prompt and records the times its lines carry.

        - turn_running is whether the chat runs a turn once the range is taken
        in, read with it: a range whose lines end a turn no hook reported
        (Escape, a prompt a hook blocked) answers false, and so does the same
        range sent again after its answer was lost, until a later turn begins.

        - A session the computer holds no chat of for the caller
        (ensureTerminalChat creates it), or a computer that is not theirs, 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: appendTerminalChatSessionFile
      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: sessionID
          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: file
          required: true
          schema:
            pattern: ^(session|agent-[A-Za-z0-9_-]{1,64})$
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                bytes:
                  description: >-
                    The range's bytes, 1 byte to 4 MiB, in standard base64 with
                    its padding.
                  maxLength: 5592408
                  minLength: 1
                  pattern: >-
                    ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
                  type: string
                generation:
                  description: >-
                    The generation the range is of: the file's current one, or
                    from offset 0 the one after it, which replaces the file.
                  format: int64
                  minimum: 1
                  type: integer
                offset:
                  description: The byte offset of the range's first byte in the file.
                  format: int64
                  minimum: 0
                  type: integer
              required:
                - generation
                - offset
                - bytes
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppendedSessionFile'
          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:
    AppendedSessionFile:
      additionalProperties: false
      properties:
        file:
          description: >-
            session, the session file, or agent-<id>, a sub-agent's file Claude
            Code writes beside it.
          pattern: ^(session|agent-[A-Za-z0-9_-]{1,64})$
          type: string
        generation:
          description: >-
            The generation of the file Aether holds: 0 while it holds nothing,
            one higher each time the file was replaced.
          format: int64
          minimum: 0
          type: integer
        size:
          description: How many bytes of the generation Aether holds, from offset 0.
          format: int64
          minimum: 0
          type: integer
        tail_sha256:
          description: >-
            The lowercase hex SHA-256 of the last 64 bytes Aether holds (all of
            them when it holds fewer).
          pattern: ^[0-9a-f]{64}$
          type: string
        turn_running:
          description: >-
            Whether the chat runs a turn once Aether took the range in: false
            once the chat is idle, as the range itself may have ended its turn.
            A range sent again answers as the chat stands when it arrives.
          type: boolean
      required:
        - file
        - generation
        - size
        - tail_sha256
        - turn_running
      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
    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
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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