> ## 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 the ways a task of a project can start

> Lists the ways a new task of the project can start, in a cloud sandbox or on one of the caller's own computers: where it runs, with which agent, the models, thinking levels and modes it may choose, and whether the caller can start it now.

Use this tool when you need to:
- Choose agent_type, model, reasoning_effort and interaction_mode for createTask
- Show the labels of the agents, models, thinking levels and modes a task may start with
- See whether the account can start a task now

Examples:
- GET /projects/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/start-options

Hints:
- projectID is the project's uuid; one that is not a uuid is 422 from the schema.
- Not paged. A sandbox's items hold one option per agent a cloud sandbox runs and a new selection may name, in the catalog's order (today codex and claude-code). An agent retired from new selections (today opencode) is listed only where a chat of the task already runs it. Each has machine ({"kind": "sandbox"} or {"kind": "computer", "computer_id": "..."}, exactly what a create will send as its machine; options with an equal machine are one place, offered once with a choice of agent), machine_label, agent_type, agent_label, can, choices and defaults.
- A computer's items hold one option per agent Aether runs on a person's computer (today claude-code). Its choices are what the agent's own CLI takes there: model default, the agent's own default there, then the models its CLI names (fable, opus, sonnet, haiku), each with thinking levels low to max, interaction mode default alone and no attachment types. Its defaults are model default, a null reasoning_effort and interaction_mode default: the computer's own settings. can.start reads unsupported with computer_cli_outdated or no_work_tree_folder when the computer's aether CLI cannot start a task, not_now with computer_unreachable, agent_starts_off or no_checkout_on_computer while it cannot now, and not_permitted credential_kind_not_admitted for a client app's grant or an agent. An agent the computer's bridge found signed out or missing reads available with the note not_signed_in or agent_not_installed: the start waits on the computer until it is put right. can.compose is what the bridge declared a run of the agent supports, and can.change_pr_automation reads unsupported pr_automation_unsupported.
- choices.models holds each model (id, label, selectable) with reasoning_efforts, the thinking levels it takes (id, label, description, selectable), empty when it takes none, and default_reasoning_effort, the words for what a null reasoning_effort runs (Codex chooses the level itself; Claude Code and OpenCode run their default level), null when it takes none. choices.interaction_modes holds each mode (id, label) and choices.attachment_types the media types a message may attach. Ids are open strings: show the label of an id you do not know.
- defaults is what a picker starts on: model, reasoning_effort (the agent's default level, null when the default model takes none) and interaction_mode. A request may also send no reasoning_effort, and the model's default_reasoning_effort says what that means. createTask and createTaskChat still require model and interaction_mode; a later change makes a create that leaves them out run with defaults.
- can holds start (whether a task or chat can be started with the option now: not_now or not_permitted with the account's standing, such as billing_blocked or org_suspended), compose (what its first message may carry: attach, reference_files, use_slash_commands, change_model, change_reasoning_effort, change_interaction_mode and change_connection) and change_pr_automation (whether the pull-request switches apply). Each is available with its notes, or not_now, unsupported or not_permitted with a reason: a code, an open set, and a sentence.
- VM sizes are getProjectRuntimeOptions', and the inference accounts an agent runs on are listConnections'. Computers are listComputers'.
- Every sandbox item comes before any computer item, and only the caller's own computers are listed: a computer lists its items whether or not it can start the task now. A computer can.start reads unsupported project_has_no_repository in a project with no repository, and not_now no_checkout_on_computer when Aether knows no checkout of the project's repository there.
- Every model and level is selectable here, and no retired agent is listed. can is for a task the caller would create, as the caller's credential may start it, the account's standing read for the cheapest VM size getProjectRuntimeOptions lists, so can.start says whether a task can start at any size; a create at a size the balance does not cover is refused with 402 credits_exhausted.
- Any owner, admin, member or viewer of the project's organization may call it: a viewer reads can.start not_permitted with org_role_insufficient. A billing member is refused with 403 org_role_insufficient, a suspended organization with 403 org_suspended, and a project that does not exist, is archived or is in an organization the caller does not belong to is 404; 503 when the membership check is unavailable.



## OpenAPI

````yaml api-reference/openapi.json GET /projects/{projectID}/start-options
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /projects/{projectID}/start-options:
    get:
      tags:
        - projects
      summary: List the ways a task of a project can start
      description: >-
        Lists the ways a new task of the project can start, in a cloud sandbox
        or on one of the caller's own computers: where it runs, with which
        agent, the models, thinking levels and modes it may choose, and whether
        the caller can start it now.


        Use this tool when you need to:

        - Choose agent_type, model, reasoning_effort and interaction_mode for
        createTask

        - Show the labels of the agents, models, thinking levels and modes a
        task may start with

        - See whether the account can start a task now


        Examples:

        - GET /projects/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/start-options


        Hints:

        - projectID is the project's uuid; one that is not a uuid is 422 from
        the schema.

        - Not paged. A sandbox's items hold one option per agent a cloud sandbox
        runs and a new selection may name, in the catalog's order (today codex
        and claude-code). An agent retired from new selections (today opencode)
        is listed only where a chat of the task already runs it. Each has
        machine ({"kind": "sandbox"} or {"kind": "computer", "computer_id":
        "..."}, exactly what a create will send as its machine; options with an
        equal machine are one place, offered once with a choice of agent),
        machine_label, agent_type, agent_label, can, choices and defaults.

        - A computer's items hold one option per agent Aether runs on a person's
        computer (today claude-code). Its choices are what the agent's own CLI
        takes there: model default, the agent's own default there, then the
        models its CLI names (fable, opus, sonnet, haiku), each with thinking
        levels low to max, interaction mode default alone and no attachment
        types. Its defaults are model default, a null reasoning_effort and
        interaction_mode default: the computer's own settings. can.start reads
        unsupported with computer_cli_outdated or no_work_tree_folder when the
        computer's aether CLI cannot start a task, not_now with
        computer_unreachable, agent_starts_off or no_checkout_on_computer while
        it cannot now, and not_permitted credential_kind_not_admitted for a
        client app's grant or an agent. An agent the computer's bridge found
        signed out or missing reads available with the note not_signed_in or
        agent_not_installed: the start waits on the computer until it is put
        right. can.compose is what the bridge declared a run of the agent
        supports, and can.change_pr_automation reads unsupported
        pr_automation_unsupported.

        - choices.models holds each model (id, label, selectable) with
        reasoning_efforts, the thinking levels it takes (id, label, description,
        selectable), empty when it takes none, and default_reasoning_effort, the
        words for what a null reasoning_effort runs (Codex chooses the level
        itself; Claude Code and OpenCode run their default level), null when it
        takes none. choices.interaction_modes holds each mode (id, label) and
        choices.attachment_types the media types a message may attach. Ids are
        open strings: show the label of an id you do not know.

        - defaults is what a picker starts on: model, reasoning_effort (the
        agent's default level, null when the default model takes none) and
        interaction_mode. A request may also send no reasoning_effort, and the
        model's default_reasoning_effort says what that means. createTask and
        createTaskChat still require model and interaction_mode; a later change
        makes a create that leaves them out run with defaults.

        - can holds start (whether a task or chat can be started with the option
        now: not_now or not_permitted with the account's standing, such as
        billing_blocked or org_suspended), compose (what its first message may
        carry: attach, reference_files, use_slash_commands, change_model,
        change_reasoning_effort, change_interaction_mode and change_connection)
        and change_pr_automation (whether the pull-request switches apply). Each
        is available with its notes, or not_now, unsupported or not_permitted
        with a reason: a code, an open set, and a sentence.

        - VM sizes are getProjectRuntimeOptions', and the inference accounts an
        agent runs on are listConnections'. Computers are listComputers'.

        - Every sandbox item comes before any computer item, and only the
        caller's own computers are listed: a computer lists its items whether or
        not it can start the task now. A computer can.start reads unsupported
        project_has_no_repository in a project with no repository, and not_now
        no_checkout_on_computer when Aether knows no checkout of the project's
        repository there.

        - Every model and level is selectable here, and no retired agent is
        listed. can is for a task the caller would create, as the caller's
        credential may start it, the account's standing read for the cheapest VM
        size getProjectRuntimeOptions lists, so can.start says whether a task
        can start at any size; a create at a size the balance does not cover is
        refused with 402 credits_exhausted.

        - Any owner, admin, member or viewer of the project's organization may
        call it: a viewer reads can.start not_permitted with
        org_role_insufficient. A billing member is refused with 403
        org_role_insufficient, a suspended organization with 403 org_suspended,
        and a project that does not exist, is archived or is in an organization
        the caller does not belong to is 404; 503 when the membership check is
        unavailable.
      operationId: getProjectStartOptions
      parameters:
        - in: path
          name: projectID
          required: true
          schema:
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListStartOption'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ProjectsErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsErrorResponse'
          description: Service Unavailable
components:
  schemas:
    ListStartOption:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/StartOption'
          type: array
      required:
        - items
      type: object
    ProjectsErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unavailable
            - aether_inference_unserved
            - agent_connector_not_found
            - agent_default_project_archived
            - agent_profile_changed
            - agent_profile_harness_fixed
            - bad_gateway
            - bad_request
            - cli_upgrade_required
            - client_outdated
            - conflict
            - connection_agent_only
            - connection_harness_mismatch
            - connection_not_held
            - control_forbidden
            - default_skill_required
            - fallback_is_own_connection
            - fallback_required_with_pin
            - fallback_requires_pin
            - forbidden
            - gateway_timeout
            - gone
            - integration_auth_unexpected
            - integration_not_in_directory
            - integration_shape_changed
            - internal_error
            - mcp_connection_github_not_connected
            - mcp_connection_oauth_not_accepted
            - mcp_connection_org_not_offered
            - mcp_connection_secret_invalid
            - mcp_connection_server_changed
            - mcp_connection_static_secret_not_accepted
            - mcp_credential_policy_not_applicable
            - mcp_credential_policy_org_unavailable
            - mcp_credential_policy_required
            - mcp_oauth_app_auth_method_unsupported
            - mcp_oauth_app_invalid
            - mcp_oauth_app_issuer_invalid
            - mcp_oauth_app_required
            - mcp_oauth_not_advertised
            - mcp_oauth_pkce_unsupported
            - mcp_oauth_registration_failed
            - mcp_repo_config_invalid
            - mcp_server_address_refused
            - mcp_server_aether_managed
            - mcp_server_api_key_not_applicable
            - mcp_server_args_invalid
            - mcp_server_auth_discovery_failed
            - mcp_server_auth_unsupported
            - mcp_server_directory_managed
            - mcp_server_directory_moved
            - mcp_server_display_name_invalid
            - mcp_server_env_invalid
            - mcp_server_headers_invalid
            - mcp_server_key_invalid
            - mcp_server_key_reserved
            - mcp_server_key_taken
            - mcp_server_kind_change_refused
            - mcp_server_not_from_directory
            - mcp_server_not_mcp
            - mcp_server_package_invalid
            - mcp_server_plugin_bundled
            - mcp_server_plugin_off
            - mcp_server_response_too_large
            - mcp_server_return_to_invalid
            - mcp_server_runtime_invalid
            - mcp_server_switched_off
            - mcp_server_unreachable
            - mcp_server_url_invalid
            - mcp_server_version_unpinned
            - method_not_allowed
            - not_acceptable
            - not_found
            - not_implemented
            - org_role_insufficient
            - org_suspended
            - payment_required
            - plugin_moved
            - plugin_name_taken
            - plugin_request_invalid
            - plugin_server_key_reserved
            - plugin_server_key_taken
            - plugin_server_probe_failed
            - plugin_server_required
            - plugin_skill_invalid
            - plugin_source_address_refused
            - plugin_source_empty
            - plugin_source_invalid
            - plugin_source_not_found
            - plugin_source_not_public
            - plugin_source_too_large
            - plugin_source_unreachable
            - plugin_source_unsupported
            - plugin_switched_off
            - plugin_undeliverable
            - pr_review_actor_deleting
            - pr_review_actor_not_member
            - pr_review_actor_required
            - pr_review_required_by_merge_when_ready
            - precondition_failed
            - project_archived
            - project_has_no_repository
            - project_unarchive_conflict
            - rate_limited
            - request_canceled
            - request_timeout
            - request_too_large
            - service_unavailable
            - skill_slug_reserved
            - unauthenticated
            - unsupported_media_type
            - validation_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
    StartOption:
      additionalProperties: false
      properties:
        agent_label:
          description: The agent's label.
          minLength: 1
          type: string
        agent_type:
          $ref: '#/components/schemas/AgentType'
        can:
          $ref: '#/components/schemas/StartAbilities'
        choices:
          $ref: '#/components/schemas/StartChoices'
        defaults:
          $ref: '#/components/schemas/StartDefaults'
        machine:
          $ref: '#/components/schemas/StartMachine'
        machine_label:
          description: The machine's label.
          minLength: 1
          type: string
      required:
        - machine
        - machine_label
        - can
        - agent_type
        - agent_label
        - choices
        - 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
    AgentType:
      description: >-
        The agent harness that runs a task, a profile or a connection:
        claude-code or claude_code is Claude Code, codex is Codex, opencode is
        OpenCode.
      enum:
        - codex
        - claude-code
        - opencode
        - claude_code
      type: string
    StartAbilities:
      additionalProperties: false
      description: >-
        What the caller can do with a start option as things stand: start,
        starting a task or chat with it now; compose, what its first message may
        carry; change_pr_automation, whether the pull-request switches
        (auto_fix_ci, auto_fix_pr_comments, auto_rebase, post_pr_screenshots,
        post_pr_demo_video, merge_when_ready) apply.
      properties:
        change_pr_automation:
          $ref: '#/components/schemas/Ability'
        compose:
          $ref: '#/components/schemas/ComposeAbilities'
        start:
          $ref: '#/components/schemas/Ability'
      required:
        - start
        - compose
        - change_pr_automation
      type: object
    StartChoices:
      additionalProperties: false
      properties:
        attachment_types:
          description: The media types a message may attach.
          items:
            type: string
          type: array
        interaction_modes:
          items:
            $ref: '#/components/schemas/ChoiceInteractionMode'
          type: array
        models:
          description: Each model with the thinking levels it takes.
          items:
            $ref: '#/components/schemas/ChoiceModel'
          type: array
      required:
        - models
        - interaction_modes
        - attachment_types
      type: object
    StartDefaults:
      additionalProperties: false
      description: >-
        What a picker starts on: the agent's own default model, thinking level
        and mode, the same in every project. Never a project's stored
        task_defaults, which a project read carries.
      properties:
        interaction_mode:
          description: The agent's default mode.
          pattern: ^[a-z][a-z0-9_]{0,31}$
          type: string
        model:
          description: The agent's default model.
          pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
          type: string
        reasoning_effort:
          description: >-
            The agent's default thinking level, which a picker starts on; null
            when the default model takes none. A request may also send no level:
            the model's default_reasoning_effort says what that means.
          pattern: ^[a-z][a-z0-9_]{0,31}$
          type:
            - string
            - 'null'
      required:
        - model
        - reasoning_effort
        - interaction_mode
      type: object
    StartMachine:
      description: >-
        Where a start option runs, a union on kind: sandbox, a cloud sandbox
        Aether runs, or computer, one of the caller's own computers. Options
        with an equal machine are one place, offered once with a choice of
        agent.
      discriminator:
        mapping:
          computer: '#/components/schemas/StartMachineComputer'
          sandbox: '#/components/schemas/StartMachineSandbox'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/StartMachineSandbox'
        - $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'
    ComposeAbilities:
      additionalProperties: false
      description: >-
        What a message to a chat, or a new chat, may carry: attach, files
        attached to a message; reference_files, files of the repository a
        message references; use_slash_commands, a message that starts with /;
        change_model, the chat's model; change_reasoning_effort, its thinking
        level; change_interaction_mode, its mode; change_connection, the
        inference account it runs on.
      properties:
        attach:
          $ref: '#/components/schemas/Ability'
        change_connection:
          $ref: '#/components/schemas/Ability'
        change_interaction_mode:
          $ref: '#/components/schemas/Ability'
        change_model:
          $ref: '#/components/schemas/Ability'
        change_reasoning_effort:
          $ref: '#/components/schemas/Ability'
        reference_files:
          $ref: '#/components/schemas/Ability'
        use_slash_commands:
          $ref: '#/components/schemas/Ability'
      required:
        - attach
        - change_connection
        - change_interaction_mode
        - change_model
        - change_reasoning_effort
        - reference_files
        - use_slash_commands
      type: object
    ChoiceInteractionMode:
      additionalProperties: false
      properties:
        id:
          description: >-
            The mode's id, what a request names as interaction_mode: an open
            string.
          pattern: ^[a-z][a-z0-9_]{0,31}$
          type: string
        label:
          minLength: 1
          type: string
      required:
        - id
        - label
      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
    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
    StartMachineSandbox:
      additionalProperties: false
      description: A cloud sandbox Aether runs.
      properties:
        kind:
          enum:
            - sandbox
          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
    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
    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.