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

# Read a task a computer is to start

> Reads a start of a task on the caller's computer, by the id of the start_task command that named it: the work tree to make (the task's own branch from origin's base branch, added from the person's checkout of the repository, at the start's folder) and the id of the Claude Code session the task's main chat is.

Use this tool when you need to:
- Carry out a start_task command: read the start it names, make its work tree, and report it with reportComputerTaskStart

Examples:
- GET /computers/{computerID}/task-starts/{startID}

Hints:
- Make the work tree only while state is pending; a prepared start's first message (first_message_id) runs as the main chat's first run, and a failed start is settled.
- A pending start waits while the computer does not let Aether start agents: it is refused with 409 agent_starts_off, and listComputerTaskStarts lists it once the computer turns that on.
- 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 GET /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}:
    get:
      tags:
        - computers
      summary: Read a task a computer is to start
      description: >-
        Reads a start of a task on the caller's computer, by the id of the
        start_task command that named it: the work tree to make (the task's own
        branch from origin's base branch, added from the person's checkout of
        the repository, at the start's folder) and the id of the Claude Code
        session the task's main chat is.


        Use this tool when you need to:

        - Carry out a start_task command: read the start it names, make its work
        tree, and report it with reportComputerTaskStart


        Examples:

        - GET /computers/{computerID}/task-starts/{startID}


        Hints:

        - Make the work tree only while state is pending; a prepared start's
        first message (first_message_id) runs as the main chat's first run, and
        a failed start is settled.

        - A pending start waits while the computer does not let Aether start
        agents: it is refused with 409 agent_starts_off, and
        listComputerTaskStarts lists it once the computer turns that on.

        - 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: getComputerTaskStart
      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
      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.