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

# Set the fallback of a harness's default connection

> Writes the fallback a task on one of the caller's plans for a harness continues on when the plan's window is spent, and keeps the harness's default.

Use this tool when you need to:
- Set or change the fallback a task continues on when its plan's window is spent
- Clear the fallback, so a task on a spent plan stops

Examples:
- PATCH /connections/defaults/codex {"fallback": {"mode": "any_usable", "then": {"runs_on": "aether"}}}
- PATCH /connections/defaults/claude-code {"fallback": {"mode": "none"}}

Hints:
- harness is claude-code, codex or opencode (the schema answers 422 for any other). fallback is required: mode none stops; named takes its connection or Aether inference as a last hop; any_usable tries the caller's held connections of this harness that no limit blocks for the task's model, then its optional named then hop. Returns the harness's default with the fallback as written.
- A task born on a profile that pins a plan follows that profile's fallback, none included, while it fails on the profile's pin or where a move under that profile put it, and never reads this one there (patchAgentProfile sets a profile's fallback); moved off that path, it reads this one. The fallback is read when a plan's window is spent, so the change reaches the caller's existing tasks on a plan too.
- Use setDefaultConnection instead to choose the default itself, with or without its fallback, and listConnectionDefaults to read the current defaults.
- Any signed-in user, for their own defaults; through a platform API key pinned to an org where the caller is a viewer or billing member it is refused with 403 org_role_insufficient, and an agent host's grant with 403 agent_host_route_not_allowed.
- Refused with 409 no_default_connection on a harness without a default, and for the named hop as setDefaultConnection refuses a default: 409 aether_inference_unserved, 409 aether_inference_unavailable, 404 connection_not_found, 409 connection_harness_mismatch, 409 connection_agent_only (or 500 where its stored row does not read), and 409 fallback_is_own_connection for a fallback naming the default's own connection.



## OpenAPI

````yaml api-reference/openapi.json PATCH /connections/defaults/{harness}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /connections/defaults/{harness}:
    patch:
      tags:
        - connections
      summary: Set the fallback of a harness's default connection
      description: >-
        Writes the fallback a task on one of the caller's plans for a harness
        continues on when the plan's window is spent, and keeps the harness's
        default.


        Use this tool when you need to:

        - Set or change the fallback a task continues on when its plan's window
        is spent

        - Clear the fallback, so a task on a spent plan stops


        Examples:

        - PATCH /connections/defaults/codex {"fallback": {"mode": "any_usable",
        "then": {"runs_on": "aether"}}}

        - PATCH /connections/defaults/claude-code {"fallback": {"mode": "none"}}


        Hints:

        - harness is claude-code, codex or opencode (the schema answers 422 for
        any other). fallback is required: mode none stops; named takes its
        connection or Aether inference as a last hop; any_usable tries the
        caller's held connections of this harness that no limit blocks for the
        task's model, then its optional named then hop. Returns the harness's
        default with the fallback as written.

        - A task born on a profile that pins a plan follows that profile's
        fallback, none included, while it fails on the profile's pin or where a
        move under that profile put it, and never reads this one there
        (patchAgentProfile sets a profile's fallback); moved off that path, it
        reads this one. The fallback is read when a plan's window is spent, so
        the change reaches the caller's existing tasks on a plan too.

        - Use setDefaultConnection instead to choose the default itself, with or
        without its fallback, and listConnectionDefaults to read the current
        defaults.

        - Any signed-in user, for their own defaults; through a platform API key
        pinned to an org where the caller is a viewer or billing member it is
        refused with 403 org_role_insufficient, and an agent host's grant with
        403 agent_host_route_not_allowed.

        - Refused with 409 no_default_connection on a harness without a default,
        and for the named hop as setDefaultConnection refuses a default: 409
        aether_inference_unserved, 409 aether_inference_unavailable, 404
        connection_not_found, 409 connection_harness_mismatch, 409
        connection_agent_only (or 500 where its stored row does not read), and
        409 fallback_is_own_connection for a fallback naming the default's own
        connection.
      operationId: patchDefaultConnection
      parameters:
        - in: path
          name: harness
          required: true
          schema:
            $ref: '#/components/schemas/AgentType'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                fallback:
                  $ref: '#/components/schemas/ConnectionFallbackWrite'
              required:
                - fallback
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionDefault'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Internal Server Error
components:
  schemas:
    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
    ConnectionFallbackWrite:
      description: >-
        What a task continues on when its plan's window is spent: none stops it;
        named takes the connection or Aether inference; any_usable takes the
        first held connection the window does not block, then its optional named
        hop.
      discriminator:
        mapping:
          any_usable: '#/components/schemas/ConnectionFallbackWriteAnyUsable'
          named: '#/components/schemas/ConnectionFallbackWriteNamed'
          none: '#/components/schemas/ConnectionFallbackNone'
        propertyName: mode
      oneOf:
        - $ref: '#/components/schemas/ConnectionFallbackNone'
        - $ref: '#/components/schemas/ConnectionFallbackWriteNamed'
        - $ref: '#/components/schemas/ConnectionFallbackWriteAnyUsable'
    ConnectionDefault:
      additionalProperties: false
      properties:
        connection_id:
          description: The connection a stored default runs on.
          format: uuid
          type: string
        fallback:
          $ref: '#/components/schemas/ConnectionFallback'
        harness:
          $ref: '#/components/schemas/AgentType'
        runs_on:
          description: >-
            aether, Aether inference, paid from your organization's balance;
            stored, the connection connection_id names.
          enum:
            - aether
            - stored
          type: string
      required:
        - harness
        - runs_on
        - fallback
      type: object
    ConnectionsErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - aether_inference_unavailable
            - aether_inference_unserved
            - agent_credential_unreadable
            - agent_host_account_deleting
            - agent_host_command_not_found
            - agent_host_creation_disabled
            - agent_host_exists
            - agent_host_illegal_transition
            - agent_host_not_allowlisted
            - agent_host_not_found
            - agent_host_other_provider_app
            - agent_host_project_not_eligible
            - agent_host_provisioning_failed
            - agent_host_state_changed
            - agent_host_wake_failed
            - agent_line_unavailable
            - bad_gateway
            - bad_request
            - cli_upgrade_required
            - client_outdated
            - conflict
            - connection_account_held
            - connection_agent_only
            - connection_harness_mismatch
            - connection_is_default
            - connection_name_taken
            - connection_not_found
            - connection_option_mismatch
            - connection_runs_agent
            - connection_runs_profiles
            - device_auth_not_found
            - fallback_is_own_connection
            - forbidden
            - gateway_timeout
            - gone
            - internal_error
            - line_exists
            - line_not_found
            - line_not_imessage
            - method_not_allowed
            - no_default_connection
            - 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
            - whatsapp_not_enabled
          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
    ConnectionFallbackWriteAnyUsable:
      additionalProperties: false
      properties:
        mode:
          enum:
            - any_usable
          type: string
        then:
          discriminator:
            mapping:
              aether: '#/components/schemas/ConnectionFallbackWriteAether'
              stored: '#/components/schemas/ConnectionFallbackWriteStored'
            propertyName: runs_on
          oneOf:
            - $ref: '#/components/schemas/ConnectionFallbackWriteAether'
            - $ref: '#/components/schemas/ConnectionFallbackWriteStored'
      required:
        - mode
      type: object
    ConnectionFallbackWriteNamed:
      discriminator:
        mapping:
          aether: '#/components/schemas/ConnectionFallbackWriteNamedAether'
          stored: '#/components/schemas/ConnectionFallbackWriteNamedStored'
        propertyName: runs_on
      oneOf:
        - $ref: '#/components/schemas/ConnectionFallbackWriteNamedAether'
        - $ref: '#/components/schemas/ConnectionFallbackWriteNamedStored'
    ConnectionFallbackNone:
      additionalProperties: false
      properties:
        mode:
          enum:
            - none
          type: string
      required:
        - mode
      type: object
    ConnectionFallback:
      description: >-
        What a task continues on when its plan's window is spent: none stops it;
        named takes the connection or Aether inference; any_usable takes the
        first held connection the window does not block, then its optional named
        hop. A stored named hop without connection_id was disconnected.
      discriminator:
        mapping:
          any_usable: '#/components/schemas/ConnectionFallbackAnyUsable'
          named: '#/components/schemas/ConnectionFallbackNamed'
          none: '#/components/schemas/ConnectionFallbackNone'
        propertyName: mode
      oneOf:
        - $ref: '#/components/schemas/ConnectionFallbackNone'
        - $ref: '#/components/schemas/ConnectionFallbackNamed'
        - $ref: '#/components/schemas/ConnectionFallbackAnyUsable'
    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
    ConnectionFallbackWriteAether:
      additionalProperties: false
      properties:
        runs_on:
          description: >-
            Aether inference, paid from your organization's balance: Claude Code
            and Codex only.
          enum:
            - aether
          type: string
      required:
        - runs_on
      type: object
    ConnectionFallbackWriteStored:
      additionalProperties: false
      properties:
        connection_id:
          description: A connection you hold that works with the harness.
          format: uuid
          type: string
        runs_on:
          description: The connection connection_id names.
          enum:
            - stored
          type: string
      required:
        - runs_on
        - connection_id
      type: object
    ConnectionFallbackWriteNamedAether:
      additionalProperties: false
      properties:
        mode:
          enum:
            - named
          type: string
        runs_on:
          description: >-
            Aether inference, paid from your organization's balance: Claude Code
            and Codex only.
          enum:
            - aether
          type: string
      required:
        - mode
        - runs_on
      type: object
    ConnectionFallbackWriteNamedStored:
      additionalProperties: false
      properties:
        connection_id:
          description: A connection you hold that works with the harness.
          format: uuid
          type: string
        mode:
          enum:
            - named
          type: string
        runs_on:
          description: The connection connection_id names.
          enum:
            - stored
          type: string
      required:
        - mode
        - runs_on
        - connection_id
      type: object
    ConnectionFallbackAnyUsable:
      additionalProperties: false
      properties:
        mode:
          enum:
            - any_usable
          type: string
        then:
          discriminator:
            mapping:
              aether: '#/components/schemas/ConnectionFallbackAether'
              stored: '#/components/schemas/ConnectionFallbackStored'
            propertyName: runs_on
          oneOf:
            - $ref: '#/components/schemas/ConnectionFallbackAether'
            - $ref: '#/components/schemas/ConnectionFallbackStored'
      required:
        - mode
      type: object
    ConnectionFallbackNamed:
      discriminator:
        mapping:
          aether: '#/components/schemas/ConnectionFallbackNamedAether'
          stored: '#/components/schemas/ConnectionFallbackNamedStored'
        propertyName: runs_on
      oneOf:
        - $ref: '#/components/schemas/ConnectionFallbackNamedAether'
        - $ref: '#/components/schemas/ConnectionFallbackNamedStored'
    ConnectionFallbackAether:
      additionalProperties: false
      properties:
        runs_on:
          description: >-
            Aether inference, paid from your organization's balance: Claude Code
            and Codex only.
          enum:
            - aether
          type: string
      required:
        - runs_on
      type: object
    ConnectionFallbackStored:
      additionalProperties: false
      properties:
        connection_id:
          description: A connection you hold that works with the harness.
          format: uuid
          type: string
        runs_on:
          description: The connection connection_id names.
          enum:
            - stored
          type: string
      required:
        - runs_on
      type: object
    ConnectionFallbackNamedAether:
      additionalProperties: false
      properties:
        mode:
          enum:
            - named
          type: string
        runs_on:
          description: >-
            Aether inference, paid from your organization's balance: Claude Code
            and Codex only.
          enum:
            - aether
          type: string
      required:
        - mode
        - runs_on
      type: object
    ConnectionFallbackNamedStored:
      additionalProperties: false
      properties:
        connection_id:
          description: A connection you hold that works with the harness.
          format: uuid
          type: string
        mode:
          enum:
            - named
          type: string
        runs_on:
          description: The connection connection_id names.
          enum:
            - stored
          type: string
      required:
        - mode
        - runs_on
      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.