> ## 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 each agent's models, thinking levels and modes

> Lists each agent a new task may start with, with the models, thinking levels and modes it may choose and its own defaults, for a screen with no project.

Use this tool when you need to:
- Choose agent_type, model and reasoning_effort for an agent profile (createAgentProfile, patchAgentProfile)
- Choose agent_type, model and interaction_mode for the onboarding task (launchOnboardingTask)
- Show the labels of the agents, models, thinking levels and modes

Examples:
- GET /agent-choices

Hints:
- Takes no parameters. Not paged: items holds one entry 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 not listed. Each has agent_type, agent_label, choices and defaults.
- choices is a start option's: 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, null when it takes none. interaction_modes holds each mode (id, label) and attachment_types the media types a message may attach. Every model and level listed here is selectable. Ids are open strings: show the label of an id you do not know.
- defaults is the agent's own default model, reasoning_effort (null when the default model takes none) and interaction_mode, the same in every project, never a project's stored task defaults.
- What an agent may choose is the same in every project and for every caller, so this reads no project, organization or standing. getProjectStartOptions lists the same entries for a project with where each runs and what the caller can do with it.
- Any signed-in person may call it, with a session or an API key; a caller who is not signed in is refused with 401.



## OpenAPI

````yaml api-reference/openapi.json GET /agent-choices
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /agent-choices:
    get:
      tags:
        - agent-choices
      summary: List each agent's models, thinking levels and modes
      description: >-
        Lists each agent a new task may start with, with the models, thinking
        levels and modes it may choose and its own defaults, for a screen with
        no project.


        Use this tool when you need to:

        - Choose agent_type, model and reasoning_effort for an agent profile
        (createAgentProfile, patchAgentProfile)

        - Choose agent_type, model and interaction_mode for the onboarding task
        (launchOnboardingTask)

        - Show the labels of the agents, models, thinking levels and modes


        Examples:

        - GET /agent-choices


        Hints:

        - Takes no parameters. Not paged: items holds one entry 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 not listed. Each has agent_type, agent_label,
        choices and defaults.

        - choices is a start option's: 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, null when it takes none. interaction_modes holds each mode (id,
        label) and attachment_types the media types a message may attach. Every
        model and level listed here is selectable. Ids are open strings: show
        the label of an id you do not know.

        - defaults is the agent's own default model, reasoning_effort (null when
        the default model takes none) and interaction_mode, the same in every
        project, never a project's stored task defaults.

        - What an agent may choose is the same in every project and for every
        caller, so this reads no project, organization or standing.
        getProjectStartOptions lists the same entries for a project with where
        each runs and what the caller can do with it.

        - Any signed-in person may call it, with a session or an API key; a
        caller who is not signed in is refused with 401.
      operationId: listAgentChoices
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentChoice'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentChoicesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentChoicesErrorResponse'
          description: Gone
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentChoicesErrorResponse'
          description: Internal Server Error
components:
  schemas:
    ListAgentChoice:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/AgentChoice'
          type: array
      required:
        - items
      type: object
    AgentChoicesErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - bad_gateway
            - bad_request
            - cli_upgrade_required
            - client_outdated
            - conflict
            - forbidden
            - gateway_timeout
            - gone
            - internal_error
            - method_not_allowed
            - not_acceptable
            - not_found
            - not_implemented
            - payment_required
            - precondition_failed
            - rate_limited
            - request_canceled
            - request_timeout
            - request_too_large
            - service_unavailable
            - 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
    AgentChoice:
      additionalProperties: false
      properties:
        agent_label:
          description: The agent's label.
          minLength: 1
          type: string
        agent_type:
          $ref: '#/components/schemas/AgentType'
        choices:
          $ref: '#/components/schemas/StartChoices'
        defaults:
          $ref: '#/components/schemas/StartDefaults'
      required:
        - 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
    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
    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
    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
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.