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

# Record a task's diff

> Keeps what the caller's machine bridge recorded of a task's work tree when a turn of one of its chats ended, by the id the bridge made for the recording, answering 204: the task's newest diff, or beside it its newest failed recording.

Use this tool when you need to:
- Record a task's diff when a turn ends, in a session open in a terminal or one the bridge runs, without being asked
- Record that there is none, and why

Examples:
- PUT /computers/{computerID}/tasks/{taskID}/diffs/{diffID} {"outcome": "recorded", "observed_at": "2026-11-15T10:00:00Z", "diff": {"base_branch": "main", "base_ref": "…", "additions": 2, "deletions": 1, "files": [...]}}
- PUT /computers/{computerID}/tasks/{taskID}/diffs/{diffID} {"outcome": "failed", "observed_at": "2026-11-15T10:00:00Z", "reason": {"code": "base_branch_gone", "message": "…"}}

Hints:
- A task keeps one recorded diff, the newest by observed_at, and its newest failure beside it: a failure never replaces a diff, and a recording no newer than the task's own changes nothing, so a repeat is harmless.
- A file is text, with its hunks, or omitted with its reason: binary; too_large once the hunks before it pass the bound; withheld when its name is a credential file's or a line of a hunk, either side or context, holds a credential's token. Never send a withheld file's content.
- More files than a recording lists, or longer paths, is the failure too_many_files, never a cut list.
- The API writes the message of every reason code it knows.
- A task backed by no work tree on 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}/tasks/{taskID}/diffs/{diffID}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/tasks/{taskID}/diffs/{diffID}:
    put:
      tags:
        - computers
      summary: Record a task's diff
      description: >-
        Keeps what the caller's machine bridge recorded of a task's work tree
        when a turn of one of its chats ended, by the id the bridge made for the
        recording, answering 204: the task's newest diff, or beside it its
        newest failed recording.


        Use this tool when you need to:

        - Record a task's diff when a turn ends, in a session open in a terminal
        or one the bridge runs, without being asked

        - Record that there is none, and why


        Examples:

        - PUT /computers/{computerID}/tasks/{taskID}/diffs/{diffID} {"outcome":
        "recorded", "observed_at": "2026-11-15T10:00:00Z", "diff":
        {"base_branch": "main", "base_ref": "…", "additions": 2, "deletions": 1,
        "files": [...]}}

        - PUT /computers/{computerID}/tasks/{taskID}/diffs/{diffID} {"outcome":
        "failed", "observed_at": "2026-11-15T10:00:00Z", "reason": {"code":
        "base_branch_gone", "message": "…"}}


        Hints:

        - A task keeps one recorded diff, the newest by observed_at, and its
        newest failure beside it: a failure never replaces a diff, and a
        recording no newer than the task's own changes nothing, so a repeat is
        harmless.

        - A file is text, with its hunks, or omitted with its reason: binary;
        too_large once the hunks before it pass the bound; withheld when its
        name is a credential file's or a line of a hunk, either side or context,
        holds a credential's token. Never send a withheld file's content.

        - More files than a recording lists, or longer paths, is the failure
        too_many_files, never a cut list.

        - The API writes the message of every reason code it knows.

        - A task backed by no work tree on 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: recordComputerTaskDiff
      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: taskID
          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: diffID
          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:
              description: >-
                What the machine bridge recorded of a task's work tree when a
                turn ended: recorded with the diff, or failed with why there is
                none.
              discriminator:
                mapping:
                  failed: '#/components/schemas/TaskDiffFailedRequest'
                  recorded: '#/components/schemas/TaskDiffRecordedRequest'
                propertyName: outcome
              oneOf:
                - $ref: '#/components/schemas/TaskDiffRecordedRequest'
                - $ref: '#/components/schemas/TaskDiffFailedRequest'
        required: true
      responses:
        '204':
          description: No Content
        '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
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Request Entity Too Large
        '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:
    TaskDiffFailedRequest:
      additionalProperties: false
      properties:
        observed_at:
          description: >-
            When the bridge diffed the work tree, on the computer's clock: the
            newest of a task's recordings stands.
          format: date-time
          type: string
        outcome:
          enum:
            - failed
          type: string
        reason:
          $ref: '#/components/schemas/TaskDiffReason'
          description: >-
            base_branch_gone: the checkout holds no such branch from origin;
            work_tree_gone: the folder is no longer the top of a git work tree,
            or is not the one the bridge holds for the task; too_many_files:
            more files differ, or their paths are longer, than a recording
            lists; git_failed: git could not diff it otherwise.
      required:
        - outcome
        - observed_at
        - reason
      type: object
    TaskDiffRecordedRequest:
      additionalProperties: false
      properties:
        diff:
          $ref: '#/components/schemas/TaskDiffBody'
        observed_at:
          description: >-
            When the bridge diffed the work tree, on the computer's clock: the
            newest of a task's recordings stands.
          format: date-time
          type: string
        outcome:
          enum:
            - recorded
          type: string
      required:
        - outcome
        - observed_at
        - diff
      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
    TaskDiffReason:
      additionalProperties: false
      properties:
        code:
          description: >-
            Why, as a word, and no closed list: an omitted file's binary,
            too_large or withheld; a failed recording's base_branch_gone,
            work_tree_gone, too_many_files or git_failed. A newer bridge may
            name another.
          maxLength: 64
          pattern: ^[a-z][a-z0-9_]*$
          type: string
        message:
          description: >-
            A sentence for a person. The API writes its own for every code it
            knows, whatever the bridge sent.
          maxLength: 1000
          minLength: 1
          pattern: \S
          type: string
      required:
        - code
        - message
      type: object
    TaskDiffBody:
      additionalProperties: false
      properties:
        additions:
          description: The text files' added lines, summed.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        base_branch:
          description: >-
            The branch on origin the diff is against, as
            getComputerWorkTreeDiffTarget names it.
          minLength: 1
          pattern: \S
          type: string
        base_ref:
          description: >-
            The merge base of HEAD and origin's base branch the diff runs from:
            a SHA-1 or SHA-256 commit.
          pattern: ^([0-9a-f]{40}|[0-9a-f]{64})$
          type: string
        deletions:
          description: The text files' deleted lines, summed.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        files:
          description: >-
            Every file the work tree changed, at most 3000 whose paths take at
            most 1048576 bytes together (more is the failure too_many_files),
            each display_path once. Their hunks take at most 1048576 bytes as a
            unified diff writes them: the file whose hunks would pass that, and
            every file after it, is omitted too_large.
          items:
            $ref: '#/components/schemas/TaskDiffFile'
          maxItems: 3000
          type: array
      required:
        - base_branch
        - base_ref
        - additions
        - deletions
        - files
      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
    TaskDiffFile:
      description: >-
        A file the work tree changed against the merge base, staged, unstaged or
        untracked alike: text, with its hunks, or omitted, with why.
      discriminator:
        mapping:
          omitted: '#/components/schemas/TaskDiffOmittedFile'
          text: '#/components/schemas/TaskDiffTextFile'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/TaskDiffTextFile'
        - $ref: '#/components/schemas/TaskDiffOmittedFile'
    TaskDiffOmittedFile:
      additionalProperties: false
      description: >-
        A file listed without its content, for its reason: binary, the file is
        binary; too_large, the diff's hunks pass the bound with this file's;
        withheld, its name is a credential file's, or a line of a hunk, either
        side or context, holds a token of a credential's format. Show the
        reason's message in place of the content.
      properties:
        display_path:
          description: new_path, or old_path for a deleted file.
          maxLength: 4096
          minLength: 1
          type: string
        kind:
          enum:
            - omitted
          type: string
        new_path:
          description: The file's path on disk; null for a deleted file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        old_path:
          description: The file's path in the merge base; null for an added file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        reason:
          $ref: '#/components/schemas/TaskDiffReason'
        status:
          description: >-
            How the file changed, a word git gives: added, modified, deleted or
            renamed, and no closed list.
          maxLength: 32
          pattern: ^[a-z][a-z0-9_]*$
          type: string
      required:
        - kind
        - status
        - old_path
        - new_path
        - display_path
        - reason
      type: object
    TaskDiffTextFile:
      additionalProperties: false
      description: A text file with its hunks.
      properties:
        additions:
          description: Its hunks' added lines.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        deletions:
          description: Its hunks' deleted lines.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        display_path:
          description: new_path, or old_path for a deleted file.
          maxLength: 4096
          minLength: 1
          type: string
        hunks:
          description: Its hunks; none for a rename alone or a mode change.
          items:
            $ref: '#/components/schemas/GitDiffHunk'
          type: array
        kind:
          enum:
            - text
          type: string
        new_path:
          description: The file's path on disk; null for a deleted file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        old_path:
          description: The file's path in the merge base; null for an added file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        status:
          description: >-
            How the file changed, a word git gives: added, modified, deleted or
            renamed, and no closed list.
          maxLength: 32
          pattern: ^[a-z][a-z0-9_]*$
          type: string
      required:
        - kind
        - status
        - old_path
        - new_path
        - display_path
        - additions
        - deletions
        - hunks
      type: object
    GitDiffHunk:
      additionalProperties: false
      description: A hunk of a file's unified diff, as the sandbox's live diff shows one.
      properties:
        header:
          description: >-
            The hunk's @@ -old_start,old_count +new_start,new_count @@ line, as
            git writes it.
          minLength: 1
          type: string
        lines:
          description: >-
            The hunk's lines, numbered from its starts: each side's lines are
            its count.
          items:
            discriminator:
              mapping:
                add: '#/components/schemas/GitDiffAddLine'
                context: '#/components/schemas/GitDiffContextLine'
                del: '#/components/schemas/GitDiffDelLine'
              propertyName: kind
            oneOf:
              - $ref: '#/components/schemas/GitDiffAddLine'
              - $ref: '#/components/schemas/GitDiffDelLine'
              - $ref: '#/components/schemas/GitDiffContextLine'
          type: array
        new_count:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        new_start:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        old_count:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        old_start:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
        - header
        - old_start
        - old_count
        - new_start
        - new_count
        - lines
      type: object
    GitDiffAddLine:
      additionalProperties: false
      description: A line the file adds.
      properties:
        kind:
          enum:
            - add
          type: string
        new_line:
          description: Its line in the new file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        no_trailing_newline:
          description: true when the line ends its side of the file with no newline.
          type: boolean
        old_line:
          type: 'null'
        text:
          description: The line, without its +, - or space and without its newline.
          type: string
      required:
        - kind
        - old_line
        - new_line
        - text
      type: object
    GitDiffContextLine:
      additionalProperties: false
      description: A line both sides hold.
      properties:
        kind:
          enum:
            - context
          type: string
        new_line:
          description: Its line in the new file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        no_trailing_newline:
          description: true when the line ends its side of the file with no newline.
          type: boolean
        old_line:
          description: Its line in the old file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        text:
          description: The line, without its +, - or space and without its newline.
          type: string
      required:
        - kind
        - old_line
        - new_line
        - text
      type: object
    GitDiffDelLine:
      additionalProperties: false
      description: A line the file deletes.
      properties:
        kind:
          enum:
            - del
          type: string
        new_line:
          type: 'null'
        no_trailing_newline:
          description: true when the line ends its side of the file with no newline.
          type: boolean
        old_line:
          description: Its line in the old file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        text:
          description: The line, without its +, - or space and without its newline.
          type: string
      required:
        - kind
        - old_line
        - new_line
        - text
      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.