> ## 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 task a computer started

> Records what the caller's machine bridge reports of a start on its computer, and answers the start as it then stands.

Use this tool when you need to:
- Report the start's work tree made: its prompt becomes the task's main chat's first message, which waits on the computer for the chat's first run (reportTerminalChatRun)
- Report that the work tree could not be made, and why

Examples:
- PUT /computers/{computerID}/task-starts/{startID} {"report": "prepared"}
- PUT /computers/{computerID}/task-starts/{startID} {"report": "failed", "reason": "base_branch_unreachable"}

Hints:
- Once prepared, the first message waits on the computer: ask to run it with reportTerminalChatRun {"report": "start"}, which starts the chat's session under the start's session_id. listTerminalChatRuns lists it once asked.
- A report the start already took answers it as it stands; any other report of a settled start is refused with 409 computer_task_start_moved.
- A report of a start Aether ended (its task was archived, it waited 24 hours from when it was written, or the sign-in or API key it was made with ended) is refused with 409 start_cancelled: remove the work tree, the local branch and the session files made for it. listComputerTaskStarts leaves such a start out, and getComputerTaskStart answers 404 not_found.
- A start not 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}/task-starts/{startID}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/task-starts/{startID}:
    put:
      tags:
        - computers
      summary: Report a task a computer started
      description: >-
        Records what the caller's machine bridge reports of a start on its
        computer, and answers the start as it then stands.


        Use this tool when you need to:

        - Report the start's work tree made: its prompt becomes the task's main
        chat's first message, which waits on the computer for the chat's first
        run (reportTerminalChatRun)

        - Report that the work tree could not be made, and why


        Examples:

        - PUT /computers/{computerID}/task-starts/{startID} {"report":
        "prepared"}

        - PUT /computers/{computerID}/task-starts/{startID} {"report": "failed",
        "reason": "base_branch_unreachable"}


        Hints:

        - Once prepared, the first message waits on the computer: ask to run it
        with reportTerminalChatRun {"report": "start"}, which starts the chat's
        session under the start's session_id. listTerminalChatRuns lists it once
        asked.

        - A report the start already took answers it as it stands; any other
        report of a settled start is refused with 409 computer_task_start_moved.

        - A report of a start Aether ended (its task was archived, it waited 24
        hours from when it was written, or the sign-in or API key it was made
        with ended) is refused with 409 start_cancelled: remove the work tree,
        the local branch and the session files made for it.
        listComputerTaskStarts leaves such a start out, and getComputerTaskStart
        answers 404 not_found.

        - A start not 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: reportComputerTaskStart
      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: startID
          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:
                reason:
                  description: >-
                    With failed, and only with it: checkout_missing when the
                    start's checkout is no checkout of the repository;
                    base_branch_unreachable when git could not fetch the base
                    branch from the checkout's origin; work_tree_failed when git
                    could not add the work tree.
                  enum:
                    - checkout_missing
                    - base_branch_unreachable
                    - work_tree_failed
                    - session_unplaced
                  type: string
                report:
                  description: >-
                    prepared once the work tree is made, on the task's branch at
                    the start's folder; failed, with reason, when it could not
                    be.
                  enum:
                    - prepared
                    - failed
                  type: string
              required:
                - report
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerTaskStart'
          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:
    ComputerTaskStart:
      description: >-
        A task started on the computer, as its machine bridge carries it out:
        the work tree to make, the session the task's main chat is, and where
        the start stands.
      discriminator:
        mapping:
          failed: '#/components/schemas/ComputerTaskStartFailed'
          pending: '#/components/schemas/ComputerTaskStartPending'
          prepared: '#/components/schemas/ComputerTaskStartPrepared'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/ComputerTaskStartPending'
        - $ref: '#/components/schemas/ComputerTaskStartPrepared'
        - $ref: '#/components/schemas/ComputerTaskStartFailed'
    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
    ComputerTaskStartFailed:
      additionalProperties: false
      description: >-
        The bridge could not make the work tree: checkout_missing,
        base_branch_unreachable or work_tree_failed; or, for a fork, could not
        place its session files: session_unplaced.
      properties:
        agent:
          description: >-
            The catalog type of the agent the task's main chat runs, such as
            claude-code. Always sent.
          minLength: 1
          type: string
        base_branch:
          description: >-
            The branch on the checkout's origin the task's branch starts from,
            and its pull request goes to.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        branch:
          description: >-
            The task's own branch, which the work tree is made on: a new task's
            is cut from base_branch on origin, a fork's is on origin already,
            pushed with the source's work.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        checkout:
          description: >-
            The person's checkout of the repository on the computer the work
            tree is added from.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        folder:
          description: The folder the work tree is made at.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        fork:
          anyOf:
            - $ref: '#/components/schemas/ComputerTaskStartFork'
            - type: 'null'
          description: >-
            The session the main chat's first run forks, for a task forked to
            the computer from another chat; null for a new task.
        id:
          description: The start's id, its start_task command's.
          format: uuid
          type: string
        prompt:
          description: The task's prompt, the main chat's first message.
          maxLength: 65536
          minLength: 1
          type: string
        reason:
          enum:
            - checkout_missing
            - base_branch_unreachable
            - work_tree_failed
            - session_unplaced
          type: string
        repository:
          $ref: '#/components/schemas/ComputerTaskStartRepository'
        session_id:
          description: >-
            The id Claude Code's session takes when the task's first run starts
            it: the task's main chat.
          format: uuid
          type: string
        state:
          enum:
            - failed
          type: string
        task_id:
          description: The task the start is of.
          format: uuid
          type: string
      required:
        - id
        - task_id
        - session_id
        - repository
        - checkout
        - folder
        - branch
        - base_branch
        - prompt
        - fork
        - state
        - reason
      type: object
    ComputerTaskStartPending:
      additionalProperties: false
      description: >-
        The bridge has not made the work tree: make it, then report it with
        reportComputerTaskStart.
      properties:
        agent:
          description: >-
            The catalog type of the agent the task's main chat runs, such as
            claude-code. Always sent.
          minLength: 1
          type: string
        base_branch:
          description: >-
            The branch on the checkout's origin the task's branch starts from,
            and its pull request goes to.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        branch:
          description: >-
            The task's own branch, which the work tree is made on: a new task's
            is cut from base_branch on origin, a fork's is on origin already,
            pushed with the source's work.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        checkout:
          description: >-
            The person's checkout of the repository on the computer the work
            tree is added from.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        folder:
          description: The folder the work tree is made at.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        fork:
          anyOf:
            - $ref: '#/components/schemas/ComputerTaskStartFork'
            - type: 'null'
          description: >-
            The session the main chat's first run forks, for a task forked to
            the computer from another chat; null for a new task.
        id:
          description: The start's id, its start_task command's.
          format: uuid
          type: string
        prompt:
          description: The task's prompt, the main chat's first message.
          maxLength: 65536
          minLength: 1
          type: string
        repository:
          $ref: '#/components/schemas/ComputerTaskStartRepository'
        session_id:
          description: >-
            The id Claude Code's session takes when the task's first run starts
            it: the task's main chat.
          format: uuid
          type: string
        state:
          enum:
            - pending
          type: string
        task_id:
          description: The task the start is of.
          format: uuid
          type: string
      required:
        - id
        - task_id
        - session_id
        - repository
        - checkout
        - folder
        - branch
        - base_branch
        - prompt
        - fork
        - state
      type: object
    ComputerTaskStartPrepared:
      additionalProperties: false
      description: >-
        The bridge made the work tree, and the prompt is the main chat's first
        message, which waits on the computer: ask to run it with
        reportTerminalChatRun, starting the session in the folder under
        session_id.
      properties:
        agent:
          description: >-
            The catalog type of the agent the task's main chat runs, such as
            claude-code. Always sent.
          minLength: 1
          type: string
        base_branch:
          description: >-
            The branch on the checkout's origin the task's branch starts from,
            and its pull request goes to.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        branch:
          description: >-
            The task's own branch, which the work tree is made on: a new task's
            is cut from base_branch on origin, a fork's is on origin already,
            pushed with the source's work.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        checkout:
          description: >-
            The person's checkout of the repository on the computer the work
            tree is added from.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        first_message_id:
          description: >-
            The main chat's first message, the prompt: the message its first run
            runs with.
          format: uuid
          type: string
        folder:
          description: The folder the work tree is made at.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        fork:
          anyOf:
            - $ref: '#/components/schemas/ComputerTaskStartFork'
            - type: 'null'
          description: >-
            The session the main chat's first run forks, for a task forked to
            the computer from another chat; null for a new task.
        id:
          description: The start's id, its start_task command's.
          format: uuid
          type: string
        prompt:
          description: The task's prompt, the main chat's first message.
          maxLength: 65536
          minLength: 1
          type: string
        repository:
          $ref: '#/components/schemas/ComputerTaskStartRepository'
        session_id:
          description: >-
            The id Claude Code's session takes when the task's first run starts
            it: the task's main chat.
          format: uuid
          type: string
        state:
          enum:
            - prepared
          type: string
        task_id:
          description: The task the start is of.
          format: uuid
          type: string
      required:
        - id
        - task_id
        - session_id
        - repository
        - checkout
        - folder
        - branch
        - base_branch
        - prompt
        - fork
        - state
        - first_message_id
      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
    ComputerTaskStartFork:
      additionalProperties: false
      description: >-
        A task forked to the computer from another chat: the session its first
        run forks, and the files the bridge places for it before it reports the
        start prepared.
      properties:
        session_id:
          description: >-
            The source's Claude Code session: place its file,
            getComputerTaskStartFile session, as <session_id>.jsonl in the
            Claude Code projects folder of the work tree's resolved folder, and
            the first run forks it with claude -p --resume <session_id>
            --fork-session --session-id <the start's session_id>.
          format: uuid
          type: string
        subagents:
          description: >-
            The source session's sub-agent files, each placed as
            <session_id>/subagents/<name>.jsonl; empty for a cloud chat's
            session.
          items:
            description: >-
              agent-<id>, a sub-agent's file Claude Code writes beside its
              session's under <session>/subagents/.
            pattern: ^agent-[A-Za-z0-9_-]{1,64}$
            type: string
          type: array
      required:
        - session_id
        - subagents
      type: object
    ComputerTaskStartRepository:
      additionalProperties: false
      properties:
        name:
          minLength: 1
          type: string
        owner:
          minLength: 1
          type: string
      required:
        - owner
        - name
      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.