> ## 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 your connections

> Lists every connection the caller holds, of every option, in the order they were added.

Use this tool when you need to:
- Find a connection's id before renaming, reconnecting or disconnecting it, or making it a default
- See which connections need re-authentication, have spent a vendor limit, or run agent profiles

Examples:
- GET /connections

Hints:
- Takes no parameters and is not paged: items holds every connection, oldest first.
- Each is a variant by option, claude_plan, anthropic_api_key, chatgpt_plan, chatgpt_host_plan (the caller's agent's own ChatGPT login, read-only), openai_api_key, openrouter_api_key or opencode_auth_file, and carries id, option, name and reauth: null while its credential works, otherwise the vendor's reason. None carries a secret.
- Where its option has one it adds email (a ChatGPT login's account, when its token names one), key_suffix (an API key's last four characters, for a key of at least eight) or providers (an OpenCode auth file's); limits (the vendor limits it has spent, less those whose reset time has passed) and profiles (the agent profiles that run on it, each with its org) appear only when there are any.
- Use listConnectionDefaults instead to read what the caller's Claude Code, Codex and OpenCode tasks run on by default, reconnectConnection to re-authenticate a connection, and renameConnection or deleteConnection to change one.
- Any signed-in user, for their own connections, an agent host's grant included; 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. A stored connection that does not decode fails the read with 500.



## OpenAPI

````yaml api-reference/openapi.json GET /connections
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /connections:
    get:
      tags:
        - connections
      summary: List your connections
      description: >-
        Lists every connection the caller holds, of every option, in the order
        they were added.


        Use this tool when you need to:

        - Find a connection's id before renaming, reconnecting or disconnecting
        it, or making it a default

        - See which connections need re-authentication, have spent a vendor
        limit, or run agent profiles


        Examples:

        - GET /connections


        Hints:

        - Takes no parameters and is not paged: items holds every connection,
        oldest first.

        - Each is a variant by option, claude_plan, anthropic_api_key,
        chatgpt_plan, chatgpt_host_plan (the caller's agent's own ChatGPT login,
        read-only), openai_api_key, openrouter_api_key or opencode_auth_file,
        and carries id, option, name and reauth: null while its credential
        works, otherwise the vendor's reason. None carries a secret.

        - Where its option has one it adds email (a ChatGPT login's account,
        when its token names one), key_suffix (an API key's last four
        characters, for a key of at least eight) or providers (an OpenCode auth
        file's); limits (the vendor limits it has spent, less those whose reset
        time has passed) and profiles (the agent profiles that run on it, each
        with its org) appear only when there are any.

        - Use listConnectionDefaults instead to read what the caller's Claude
        Code, Codex and OpenCode tasks run on by default, reconnectConnection to
        re-authenticate a connection, and renameConnection or deleteConnection
        to change one.

        - Any signed-in user, for their own connections, an agent host's grant
        included; 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. A stored connection that does not decode fails
        the read with 500.
      operationId: listConnections
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConnection'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Gone
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsErrorResponse'
          description: Internal Server Error
components:
  schemas:
    ListConnection:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/Connection'
          type: array
      required:
        - items
      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
    Connection:
      description: >-
        One connection you hold, a variant per option: which credential it
        holds, qualified by its vendor. reauth is null while the stored
        credential works.
      discriminator:
        mapping:
          anthropic_api_key: '#/components/schemas/AnthropicApiKeyConnection'
          chatgpt_host_plan: '#/components/schemas/ChatgptHostPlanConnection'
          chatgpt_plan: '#/components/schemas/ChatgptPlanConnection'
          claude_plan: '#/components/schemas/ClaudePlanConnection'
          openai_api_key: '#/components/schemas/OpenaiApiKeyConnection'
          opencode_auth_file: '#/components/schemas/OpencodeAuthFileConnection'
          openrouter_api_key: '#/components/schemas/OpenrouterApiKeyConnection'
        propertyName: option
      oneOf:
        - $ref: '#/components/schemas/ClaudePlanConnection'
        - $ref: '#/components/schemas/AnthropicApiKeyConnection'
        - $ref: '#/components/schemas/ChatgptPlanConnection'
        - $ref: '#/components/schemas/ChatgptHostPlanConnection'
        - $ref: '#/components/schemas/OpenaiApiKeyConnection'
        - $ref: '#/components/schemas/OpenrouterApiKeyConnection'
        - $ref: '#/components/schemas/OpencodeAuthFileConnection'
    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
    AnthropicApiKeyConnection:
      additionalProperties: false
      description: An Anthropic API key.
      properties:
        id:
          format: uuid
          type: string
        key_suffix:
          description: The key's last four characters, for a key of at least eight.
          minLength: 1
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - anthropic_api_key
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    ChatgptHostPlanConnection:
      additionalProperties: false
      description: >-
        The ChatGPT login your agent did on its own host. Read-only: your agent
        signs in on its host, so no operation adds or reconnects it, and only
        your agent runs on it.
      properties:
        email:
          description: The ChatGPT account's email, when its token names one.
          minLength: 1
          type: string
        id:
          format: uuid
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - chatgpt_host_plan
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    ChatgptPlanConnection:
      additionalProperties: false
      description: A ChatGPT plan's tokens.
      properties:
        email:
          description: The ChatGPT account's email, when its token names one.
          minLength: 1
          type: string
        id:
          format: uuid
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - chatgpt_plan
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    ClaudePlanConnection:
      additionalProperties: false
      description: A Claude plan's setup token.
      properties:
        id:
          format: uuid
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - claude_plan
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    OpenaiApiKeyConnection:
      additionalProperties: false
      description: An OpenAI API key.
      properties:
        id:
          format: uuid
          type: string
        key_suffix:
          description: The key's last four characters, for a key of at least eight.
          minLength: 1
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - openai_api_key
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    OpencodeAuthFileConnection:
      additionalProperties: false
      description: An OpenCode auth file.
      properties:
        id:
          format: uuid
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - opencode_auth_file
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        providers:
          description: The model providers the auth file signs in to.
          items:
            minLength: 1
            type: string
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
        - providers
      type: object
    OpenrouterApiKeyConnection:
      additionalProperties: false
      description: An OpenRouter API key.
      properties:
        id:
          format: uuid
          type: string
        key_suffix:
          description: The key's last four characters, for a key of at least eight.
          minLength: 1
          type: string
        limits:
          description: >-
            The vendor limits this connection has spent, excluding markers whose
            reset time has passed.
          items:
            discriminator:
              mapping:
                credits: '#/components/schemas/ConnectionCreditsLimit'
                model: '#/components/schemas/ConnectionModelLimit'
                session: '#/components/schemas/ConnectionSessionLimit'
                usage: '#/components/schemas/ConnectionUsageLimit'
                weekly: '#/components/schemas/ConnectionWeeklyLimit'
              propertyName: scope
            oneOf:
              - $ref: '#/components/schemas/ConnectionSessionLimit'
              - $ref: '#/components/schemas/ConnectionWeeklyLimit'
              - $ref: '#/components/schemas/ConnectionModelLimit'
              - $ref: '#/components/schemas/ConnectionCreditsLimit'
              - $ref: '#/components/schemas/ConnectionUsageLimit'
          type: array
        name:
          description: >-
            The name you gave the connection, unique among your connections of
            its option.
          minLength: 1
          type: string
        option:
          enum:
            - openrouter_api_key
          type: string
        profiles:
          description: The agent profiles that run on the connection.
          items:
            $ref: '#/components/schemas/ConnectionProfile'
          type: array
        reauth:
          anyOf:
            - $ref: '#/components/schemas/ConnectionReauth'
            - type: 'null'
      required:
        - option
        - id
        - name
        - reauth
      type: object
    ConnectionCreditsLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - credits
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionModelLimit:
      additionalProperties: false
      properties:
        model:
          minLength: 1
          type: string
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - model
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
        - model
      type: object
    ConnectionSessionLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - session
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionUsageLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - usage
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionWeeklyLimit:
      additionalProperties: false
      properties:
        reason:
          minLength: 1
          type: string
        scope:
          enum:
            - weekly
          type: string
        until:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - scope
        - until
        - reason
      type: object
    ConnectionProfile:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
        name:
          minLength: 1
          type: string
        org:
          description: The name of the organization the profile belongs to.
          minLength: 1
          type: string
      required:
        - id
        - name
        - org
      type: object
    ConnectionReauth:
      additionalProperties: false
      properties:
        reason:
          description: Why the stored credential failed, as the vendor said.
          minLength: 1
          type: string
      required:
        - reason
      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.