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

# List where a chat can be forked

> Lists where a chat can be forked, and whether the caller can fork it there now. The list is returned whole.

Use this tool when you need to:
- Offer, disable or hide a chat's Fork chat before a person chooses it
- Say why a chat cannot be forked into a new chat of its task, a new sandbox task, or a new task on one of your computers, now

Examples:
- GET /tasks/{taskID}/chats/{chatID}/fork-options
- GET /tasks/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/chats/0b8e6d52-4f3a-4c1e-9d7b-2a5c8e1f3b90/fork-options

Hints:
- taskID and chatID are lowercase uuids; a chat of another task is 404.
- The list holds one option of to kind this_task, a new chat of the chat's own task, then one of kind sandbox, a new task in a sandbox of the project's default size, then one of kind computer for each of the caller's own computers (listComputers), never another person's. to is what forkTaskChat takes. Each option has machine_label (the label of the machine the new chat runs on), can.fork, models and defaults (the model and thinking level the new chat runs with when the fork names none).
- this_task: models is empty, and defaults are the chat's own model and thinking level.
- sandbox: models are what GET /projects/{projectID}/start-options lists for the chat's agent. defaults are the chat's own model and thinking level where models lists them, else that list's default model and the model's default thinking level (null).
- can.fork is available, or not_now, unsupported or not_permitted with a reason whose message is the sentence forkTaskChat refuses with: not_now while a turn of the chat is queued or running, while its agent waits on a question or plan, and before its first turn has ended; unsupported for an OpenCode chat; not_permitted for a reader who may not act in the task's chats, or a suspended account (a suspended organization is refused the read with 403 org_suspended). The sandbox option's can.fork then reads the account's standing for a new task as GET /projects/{projectID}/start-options reads it: not_now with billing_blocked, credits_exhausted or org_task_concurrency_exceeded.
- computer: machine_label is the computer's name. models are what that computer's start option (GET /projects/{projectID}/start-options) lists for the chat's agent, and defaults the chat's own model and thinking level where they list them, else model default and no thinking level, the computer's own settings. An item that cannot be chosen because its agent runs on no computer (can.fork unsupported with fork_unsupported) lists no models, and its defaults are the chat's own: a client offers no model for it. can.fork reads the chat's own reasons first, then that start option's can.start for a fork: unsupported with fork_unsupported for an agent that cannot be continued there (only Claude Code runs on a computer, and a bridge may declare it places no fork), computer_cli_outdated for a bridge that does not start tasks or place forks, no_work_tree_folder for one that named no folder for work trees, project_has_no_repository; not_now with computer_unreachable, agent_starts_off or no_checkout_on_computer; not_permitted with credential_kind_not_admitted for a client app's grant or an agent's credential; available with the note not_signed_in or agent_not_installed when the agent there needs putting right, which the new task's start waits on.
- Any member of the task's organization may read it, a viewer included; a billing member is refused with 403 org_role_insufficient, a suspended organization with 403 org_suspended, and a task or chat outside the caller's reach is 404 not_found; 503 when the membership check is unavailable.
- A chat on its person's computer lists the same three kinds, from one read of the chat, the account's standing and the caller's computers. this_task is unsupported with chats_not_addable (not_permitted first for anyone who may not act on the chat): a task on a computer runs one chat. machine_label is the task's computer's name, and defaults are the chat's own. sandbox reads the chat's can.fork, then the account's standing; computer reads the chat's can.fork, then that computer's start option for a fork, the chat's own computer included. Each item's defaults are the chat's model and thinking level where the destination lists them, else what its session last ran on (read from the end of Aether's copy of its file) where it lists that, else the destination's default. forkTaskChat refuses each destination with the code and sentence its item shows. A deployment with no checkpoint storage answers the list, as it answers a fork of such a chat into a new task, 500 teleport_unavailable.



## OpenAPI

````yaml api-reference/openapi.json GET /tasks/{taskID}/chats/{chatID}/fork-options
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /tasks/{taskID}/chats/{chatID}/fork-options:
    get:
      tags:
        - tasks
      summary: List where a chat can be forked
      description: >-
        Lists where a chat can be forked, and whether the caller can fork it
        there now. The list is returned whole.


        Use this tool when you need to:

        - Offer, disable or hide a chat's Fork chat before a person chooses it

        - Say why a chat cannot be forked into a new chat of its task, a new
        sandbox task, or a new task on one of your computers, now


        Examples:

        - GET /tasks/{taskID}/chats/{chatID}/fork-options

        - GET
        /tasks/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/chats/0b8e6d52-4f3a-4c1e-9d7b-2a5c8e1f3b90/fork-options


        Hints:

        - taskID and chatID are lowercase uuids; a chat of another task is 404.

        - The list holds one option of to kind this_task, a new chat of the
        chat's own task, then one of kind sandbox, a new task in a sandbox of
        the project's default size, then one of kind computer for each of the
        caller's own computers (listComputers), never another person's. to is
        what forkTaskChat takes. Each option has machine_label (the label of the
        machine the new chat runs on), can.fork, models and defaults (the model
        and thinking level the new chat runs with when the fork names none).

        - this_task: models is empty, and defaults are the chat's own model and
        thinking level.

        - sandbox: models are what GET /projects/{projectID}/start-options lists
        for the chat's agent. defaults are the chat's own model and thinking
        level where models lists them, else that list's default model and the
        model's default thinking level (null).

        - can.fork is available, or not_now, unsupported or not_permitted with a
        reason whose message is the sentence forkTaskChat refuses with: not_now
        while a turn of the chat is queued or running, while its agent waits on
        a question or plan, and before its first turn has ended; unsupported for
        an OpenCode chat; not_permitted for a reader who may not act in the
        task's chats, or a suspended account (a suspended organization is
        refused the read with 403 org_suspended). The sandbox option's can.fork
        then reads the account's standing for a new task as GET
        /projects/{projectID}/start-options reads it: not_now with
        billing_blocked, credits_exhausted or org_task_concurrency_exceeded.

        - computer: machine_label is the computer's name. models are what that
        computer's start option (GET /projects/{projectID}/start-options) lists
        for the chat's agent, and defaults the chat's own model and thinking
        level where they list them, else model default and no thinking level,
        the computer's own settings. An item that cannot be chosen because its
        agent runs on no computer (can.fork unsupported with fork_unsupported)
        lists no models, and its defaults are the chat's own: a client offers no
        model for it. can.fork reads the chat's own reasons first, then that
        start option's can.start for a fork: unsupported with fork_unsupported
        for an agent that cannot be continued there (only Claude Code runs on a
        computer, and a bridge may declare it places no fork),
        computer_cli_outdated for a bridge that does not start tasks or place
        forks, no_work_tree_folder for one that named no folder for work trees,
        project_has_no_repository; not_now with computer_unreachable,
        agent_starts_off or no_checkout_on_computer; not_permitted with
        credential_kind_not_admitted for a client app's grant or an agent's
        credential; available with the note not_signed_in or agent_not_installed
        when the agent there needs putting right, which the new task's start
        waits on.

        - Any member of the task's organization may read it, a viewer included;
        a billing member is refused with 403 org_role_insufficient, a suspended
        organization with 403 org_suspended, and a task or chat outside the
        caller's reach is 404 not_found; 503 when the membership check is
        unavailable.

        - A chat on its person's computer lists the same three kinds, from one
        read of the chat, the account's standing and the caller's computers.
        this_task is unsupported with chats_not_addable (not_permitted first for
        anyone who may not act on the chat): a task on a computer runs one chat.
        machine_label is the task's computer's name, and defaults are the chat's
        own. sandbox reads the chat's can.fork, then the account's standing;
        computer reads the chat's can.fork, then that computer's start option
        for a fork, the chat's own computer included. Each item's defaults are
        the chat's model and thinking level where the destination lists them,
        else what its session last ran on (read from the end of Aether's copy of
        its file) where it lists that, else the destination's default.
        forkTaskChat refuses each destination with the code and sentence its
        item shows. A deployment with no checkpoint storage answers the list, as
        it answers a fork of such a chat into a new task, 500
        teleport_unavailable.
      operationId: getTaskChatForkOptions
      parameters:
        - 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: chatID
          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/ListForkOption'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/TasksErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Service Unavailable
components:
  schemas:
    ListForkOption:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ForkOption'
          type: array
      required:
        - items
      type: object
    TasksErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - 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_starts_no_agents
            - computer_starts_no_forks
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - creator_github_access_missing
            - 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_claim_unverified
            - github_failed
            - github_identity_mismatch
            - github_identity_required
            - github_push_access_required
            - github_reconnect_required
            - github_ref_not_found
            - 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
            - 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_turn_running
            - 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_answered_in_terminal
            - permission_prompt_expired
            - permission_prompt_open
            - permission_prompt_stopped
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_archived
            - project_has_no_repository
            - project_repo_disconnected
            - project_repository_differs
            - project_required
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - push_file_too_large
            - push_rejected
            - push_secret_detected
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - repository_administration_not_granted
            - repository_already_connected
            - repository_create_forbidden
            - repository_create_rejected
            - repository_created_not_linked
            - repository_not_connected
            - repository_owner_not_caller
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - save_in_progress
            - save_requires_task_creator
            - service_unavailable
            - session_file_missing
            - session_gone
            - session_not_started_by_aether
            - slash_command
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - stream_delivery_gap
            - stream_event_conflict
            - task_already_saved
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_bound_at_creation
            - task_branch_diverged
            - task_branch_is_default
            - task_branch_mismatch
            - task_branch_missing
            - task_connection_disconnected
            - task_creator_deleted
            - task_executing
            - task_file_too_large
            - task_has_no_branch
            - task_has_no_commits
            - task_has_no_files
            - task_has_no_repository
            - task_history_has_merges
            - task_ineligible
            - task_is_child
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_rebase_in_progress
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_run_running
            - 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
            - working_tree_dirty
            - 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
    ForkOption:
      additionalProperties: false
      properties:
        can:
          $ref: '#/components/schemas/ForkOptionAbilities'
        defaults:
          $ref: '#/components/schemas/ForkDefaults'
        machine_label:
          description: The label of the machine the new chat runs on.
          minLength: 1
          type: string
        models:
          description: >-
            The models the new chat may choose; empty when it takes the chat's
            own.
          items:
            $ref: '#/components/schemas/ChoiceModel'
          type: array
        to:
          $ref: '#/components/schemas/ForkDestination'
      required:
        - to
        - machine_label
        - can
        - models
        - defaults
      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
    ForkOptionAbilities:
      additionalProperties: false
      description: >-
        What the caller can do with a fork option as things stand: fork, forking
        the chat there now.
      properties:
        fork:
          $ref: '#/components/schemas/Ability'
      required:
        - fork
      type: object
    ForkDefaults:
      additionalProperties: false
      properties:
        model:
          minLength: 1
          type: string
        reasoning_effort:
          description: >-
            The thinking level the new chat runs with; null when it runs with
            its model's default.
          pattern: ^[a-z][a-z0-9_]{0,31}$
          type:
            - string
            - 'null'
      required:
        - model
        - reasoning_effort
      type: object
    ChoiceModel:
      additionalProperties: false
      properties:
        default_reasoning_effort:
          anyOf:
            - $ref: '#/components/schemas/ChoiceWords'
            - type: 'null'
          description: >-
            What a null thinking level means for this model, with the words to
            show for it; null when the model takes no thinking level.
        id:
          description: 'The model''s id, what a request names: an open string.'
          pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
          type: string
        label:
          minLength: 1
          type: string
        reasoning_efforts:
          description: The thinking levels the model takes; empty when it takes none.
          items:
            $ref: '#/components/schemas/ChoiceReasoningEffort'
          type: array
        selectable:
          description: >-
            False for a model a chat of the task holds that no new selection may
            name: it is listed so its label can be shown.
          type: boolean
      required:
        - id
        - label
        - selectable
        - reasoning_efforts
        - default_reasoning_effort
      type: object
    ForkDestination:
      description: >-
        Where a fork goes, a union on kind: this_task, a new chat of the chat's
        own task; sandbox, a new task in a cloud sandbox; or computer, a new
        task on one of the caller's own computers. The sandbox and computer
        members are the machine a create takes.
      discriminator:
        mapping:
          computer: '#/components/schemas/StartMachineComputer'
          sandbox: '#/components/schemas/CreateTaskMachineSandbox'
          this_task: '#/components/schemas/ForkThisTaskDestination'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/ForkThisTaskDestination'
        - $ref: '#/components/schemas/CreateTaskMachineSandbox'
        - $ref: '#/components/schemas/StartMachineComputer'
    Ability:
      discriminator:
        mapping:
          available: '#/components/schemas/AbilityAvailable'
          not_now: '#/components/schemas/AbilityNotNow'
          not_permitted: '#/components/schemas/AbilityNotPermitted'
          unsupported: '#/components/schemas/AbilityUnsupported'
        propertyName: availability
      oneOf:
        - $ref: '#/components/schemas/AbilityAvailable'
        - $ref: '#/components/schemas/AbilityNotNow'
        - $ref: '#/components/schemas/AbilityUnsupported'
        - $ref: '#/components/schemas/AbilityNotPermitted'
    ChoiceWords:
      additionalProperties: false
      description: 'The words shown for a choice: its label and a one-sentence description.'
      properties:
        description:
          minLength: 1
          type: string
        label:
          minLength: 1
          type: string
      required:
        - description
        - label
      type: object
    ChoiceReasoningEffort:
      additionalProperties: false
      properties:
        description:
          minLength: 1
          type: string
        id:
          description: >-
            The level's id, what a request names as reasoning_effort: an open
            string.
          pattern: ^[a-z][a-z0-9_]{0,31}$
          type: string
        label:
          minLength: 1
          type: string
        selectable:
          description: >-
            False for a level a chat of the task holds that no new selection may
            name: it is listed so its label can be shown.
          type: boolean
      required:
        - id
        - label
        - description
        - selectable
      type: object
    StartMachineComputer:
      additionalProperties: false
      description: One of the caller's own computers.
      properties:
        computer_id:
          format: uuid
          type: string
        kind:
          enum:
            - computer
          type: string
      required:
        - kind
        - computer_id
      type: object
    CreateTaskMachineSandbox:
      additionalProperties: false
      description: A cloud sandbox Aether runs, with its size.
      properties:
        kind:
          enum:
            - sandbox
          type: string
        vm_size:
          description: The sandbox's size. Omitted, the project's default size.
          enum:
            - medium
            - large
            - xl
          type: string
      required:
        - kind
      type: object
    ForkThisTaskDestination:
      additionalProperties: false
      description: >-
        A new chat of the chat's own task: the same files, branch and pull
        request.
      properties:
        kind:
          enum:
            - this_task
          type: string
      required:
        - kind
      type: object
    AbilityAvailable:
      additionalProperties: false
      description: The action will be carried out.
      properties:
        availability:
          enum:
            - available
          type: string
        notes:
          description: >-
            What a person reads before taking the action; empty when there is
            nothing to note.
          items:
            $ref: '#/components/schemas/AbilityMessage'
          type: array
      required:
        - availability
        - notes
      type: object
    AbilityNotNow:
      additionalProperties: false
      description: The action is possible for this chat or task, but not as things stand.
      properties:
        availability:
          enum:
            - not_now
          type: string
        reason:
          $ref: '#/components/schemas/AbilityMessage'
      required:
        - availability
        - reason
      type: object
    AbilityNotPermitted:
      additionalProperties: false
      description: The caller may not take the action.
      properties:
        availability:
          enum:
            - not_permitted
          type: string
        reason:
          $ref: '#/components/schemas/AbilityMessage'
      required:
        - availability
        - reason
      type: object
    AbilityUnsupported:
      additionalProperties: false
      description: >-
        The action is not possible for this chat or task as it is, and nothing
        the person does here changes that.
      properties:
        availability:
          enum:
            - unsupported
          type: string
        reason:
          $ref: '#/components/schemas/AbilityMessage'
      required:
        - availability
        - reason
      type: object
    AbilityMessage:
      additionalProperties: false
      description: >-
        A note on an available ability, or the reason a refused ability is
        refused.
      properties:
        code:
          description: >-
            What the note or reason is, as a code a client may branch on. An
            open set: a client shows the message of a code it does not know.
          pattern: ^[a-z][a-z0-9_]*$
          type: string
        message:
          description: A full sentence in plain text, written for the person who reads it.
          maxLength: 200
          minLength: 1
          type: string
          x-aether-string-length-unit: unicode-code-point
      required:
        - code
        - message
      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.