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

# Search integrations by name

> Searches Aether's own MCP servers, Aether's integration directory and the organization's plugin marketplaces (the official Claude Code and Codex ones) for q, one result per integration, with each source's status.

Use this tool when you need to:
- Find an integration to install by its name or what it does, such as linear or error tracking
- Learn whether the organization already installed an integration, and which plugin or server it became
- Choose the install call for a result: a directory key or a marketplace plugin

Examples:
- GET /orgs/{orgID}/integration-search?q=linear
- GET /orgs/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/integration-search?q=error%20tracking

Hints:
- q is required, 1 to 100 characters holding a non-space, matched trimmed and ignoring case: every word of it must be in an integration's name, an alias, its description or its category, or in a marketplace plugin's name or category (a plugin's description is its vendor's copy, which names other products).
- A result is kind aether, one of Aether's servers the organization's catalog holds, installed already; kind integration, an integration of the directory, installed by its key with installDirectoryIntegration; or kind plugin, one a marketplace lists, installed by the marketplace's URL and its name with installPlugin.
- Aether's servers and the directory's integrations come first, then the marketplaces' plugins, each group those matching by name or alias before the others; Aether's servers and a directory entry hide every marketplace plugin of their names, the one an entry prefers included.
- An integration's source says what it contains and its default_credential_policy whose connection it takes; a marketplace's listing does not say what a plugin bundles, which Aether reads from its files when it installs it (not_loaded_by names the agents the listing already shows would not load it).
- installed names the card of what the organization installed: one of Aether's servers; an integration's plugin or, installed as its server alone, that server; the organization's plugin of a marketplace plugin's name. It is absent for what is not installed.
- sources reports the directory, then each marketplace, with its status: a marketplace Aether could not read is unavailable, with why, and contributes no results; it is never reported as listing none. A marketplace's listing is read again once it is ten minutes old, and a marketplace that could not be read is tried again a minute later.
- Use searchIntegrationRegistry instead to search the MCP registry, which this does not search, and listIntegrationDirectory to browse without a query.
- Owners and admins of the organization; any other role is refused with 403 org_role_insufficient, a caller outside the organization with 403 org_membership_required, and an agent host's grant with 403 agent_host_route_not_allowed. A q the schema refuses (missing, empty, over 100 characters, or only spaces, tabs, newlines, form feeds and carriage returns) is a plain 422; one it admits that is still blank once trimmed (vertical tabs, or Unicode spaces such as U+00A0) is 422 plugin_request_invalid.



## OpenAPI

````yaml api-reference/openapi.json GET /orgs/{orgID}/integration-search
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /orgs/{orgID}/integration-search:
    get:
      tags:
        - plugins
      summary: Search integrations by name
      description: >-
        Searches Aether's own MCP servers, Aether's integration directory and
        the organization's plugin marketplaces (the official Claude Code and
        Codex ones) for q, one result per integration, with each source's
        status.


        Use this tool when you need to:

        - Find an integration to install by its name or what it does, such as
        linear or error tracking

        - Learn whether the organization already installed an integration, and
        which plugin or server it became

        - Choose the install call for a result: a directory key or a marketplace
        plugin


        Examples:

        - GET /orgs/{orgID}/integration-search?q=linear

        - GET
        /orgs/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/integration-search?q=error%20tracking


        Hints:

        - q is required, 1 to 100 characters holding a non-space, matched
        trimmed and ignoring case: every word of it must be in an integration's
        name, an alias, its description or its category, or in a marketplace
        plugin's name or category (a plugin's description is its vendor's copy,
        which names other products).

        - A result is kind aether, one of Aether's servers the organization's
        catalog holds, installed already; kind integration, an integration of
        the directory, installed by its key with installDirectoryIntegration; or
        kind plugin, one a marketplace lists, installed by the marketplace's URL
        and its name with installPlugin.

        - Aether's servers and the directory's integrations come first, then the
        marketplaces' plugins, each group those matching by name or alias before
        the others; Aether's servers and a directory entry hide every
        marketplace plugin of their names, the one an entry prefers included.

        - An integration's source says what it contains and its
        default_credential_policy whose connection it takes; a marketplace's
        listing does not say what a plugin bundles, which Aether reads from its
        files when it installs it (not_loaded_by names the agents the listing
        already shows would not load it).

        - installed names the card of what the organization installed: one of
        Aether's servers; an integration's plugin or, installed as its server
        alone, that server; the organization's plugin of a marketplace plugin's
        name. It is absent for what is not installed.

        - sources reports the directory, then each marketplace, with its status:
        a marketplace Aether could not read is unavailable, with why, and
        contributes no results; it is never reported as listing none. A
        marketplace's listing is read again once it is ten minutes old, and a
        marketplace that could not be read is tried again a minute later.

        - Use searchIntegrationRegistry instead to search the MCP registry,
        which this does not search, and listIntegrationDirectory to browse
        without a query.

        - Owners and admins of the organization; any other role is refused with
        403 org_role_insufficient, a caller outside the organization with 403
        org_membership_required, and an agent host's grant with 403
        agent_host_route_not_allowed. A q the schema refuses (missing, empty,
        over 100 characters, or only spaces, tabs, newlines, form feeds and
        carriage returns) is a plain 422; one it admits that is still blank once
        trimmed (vertical tabs, or Unicode spaces such as U+00A0) is 422
        plugin_request_invalid.
      operationId: searchIntegrations
      parameters:
        - in: path
          name: orgID
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            What to find: each of its words matched, ignoring case, against each
            integration's name and aliases, then its description and category; a
            marketplace plugin's against its name, then its category.
          explode: false
          in: query
          name: q
          required: true
          schema:
            description: >-
              What to find: each of its words matched, ignoring case, against
              each integration's name and aliases, then its description and
              category; a marketplace plugin's against its name, then its
              category.
            maxLength: 100
            minLength: 1
            pattern: \S
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationSearchResults'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginsErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PluginsErrorResponse'
                  - $ref: '#/components/schemas/PluginErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginsErrorResponse'
          description: Internal Server Error
components:
  schemas:
    IntegrationSearchResults:
      additionalProperties: false
      properties:
        results:
          description: >-
            One per integration whose name, aliases, description or category
            hold every word of the query (a marketplace plugin by its name and
            category alone: its description is its vendor's copy): Aether's
            servers and a directory entry hide every marketplace plugin of their
            names, the one an entry prefers included, and of the plugins
            marketplaces list under one name the first that matches is the
            result. Aether's servers and the directory's integrations come
            first, then the marketplaces' plugins, each group those whose name
            or aliases hold every word before the others; within each, Aether's
            servers, then the directory's, then each marketplace's in turn.
          items:
            $ref: '#/components/schemas/IntegrationSearchResult'
          type: array
        sources:
          description: >-
            The integration directory, then each of the organization's
            marketplaces, each with its status.
          items:
            $ref: '#/components/schemas/IntegrationSearchSource'
          type: array
      required:
        - sources
        - results
      type: object
    PluginsErrorResponse:
      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
            - 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
            - precondition_failed
            - 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
    PluginErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - plugin_request_invalid
            - plugin_source_address_refused
            - plugin_source_not_public
            - plugin_source_unreachable
            - plugin_source_not_found
            - plugin_source_unsupported
            - plugin_source_too_large
            - plugin_source_invalid
            - plugin_source_empty
            - plugin_skill_invalid
            - plugin_undeliverable
            - plugin_server_probe_failed
            - plugin_server_key_taken
            - plugin_server_key_reserved
            - plugin_name_taken
            - plugin_moved
            - plugin_server_required
            - plugin_switched_off
            - mcp_credential_policy_required
            - mcp_credential_policy_not_applicable
            - mcp_credential_policy_org_unavailable
            - integration_not_in_directory
            - integration_shape_changed
            - integration_auth_unexpected
          type: string
        conflicts:
          items:
            $ref: '#/components/schemas/PluginKeyHolder'
          type: array
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
        - conflicts
      type: object
    IntegrationSearchResult:
      discriminator:
        mapping:
          aether: '#/components/schemas/IntegrationSearchAetherResult'
          integration: '#/components/schemas/IntegrationSearchIntegrationResult'
          plugin: '#/components/schemas/IntegrationSearchPluginResult'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/IntegrationSearchAetherResult'
        - $ref: '#/components/schemas/IntegrationSearchIntegrationResult'
        - $ref: '#/components/schemas/IntegrationSearchPluginResult'
    IntegrationSearchSource:
      discriminator:
        mapping:
          directory: '#/components/schemas/IntegrationSearchDirectorySource'
          marketplace: '#/components/schemas/IntegrationSearchMarketplaceSource'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/IntegrationSearchDirectorySource'
        - $ref: '#/components/schemas/IntegrationSearchMarketplaceSource'
    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
    PluginKeyHolder:
      additionalProperties: false
      properties:
        key:
          type: string
        plugin:
          type:
            - string
            - 'null'
        source:
          enum:
            - manual
            - aether
            - plugin
            - directory
          type: string
      required:
        - key
        - source
        - plugin
      type: object
    IntegrationSearchAetherResult:
      additionalProperties: false
      properties:
        installed:
          $ref: '#/components/schemas/IntegrationSearchInstalled'
        kind:
          enum:
            - aether
          type: string
        server:
          $ref: '#/components/schemas/IntegrationSearchAetherIntegration'
      required:
        - kind
        - server
        - installed
      type: object
    IntegrationSearchIntegrationResult:
      additionalProperties: false
      properties:
        installed:
          $ref: '#/components/schemas/IntegrationSearchInstalled'
        integration:
          $ref: '#/components/schemas/DirectoryIntegration'
        kind:
          enum:
            - integration
          type: string
      required:
        - kind
        - integration
      type: object
    IntegrationSearchPluginResult:
      additionalProperties: false
      properties:
        installed:
          $ref: '#/components/schemas/IntegrationSearchInstalled'
        kind:
          enum:
            - plugin
          type: string
        marketplace:
          $ref: '#/components/schemas/PluginMarketplace'
        not_loaded_by:
          description: >-
            The agents whose tasks would run without it, where its listing
            already tells; Aether reads the rest of each agent's rules from its
            files at install.
          items:
            $ref: '#/components/schemas/IntegrationSearchRefusal'
          type: array
        plugin:
          $ref: '#/components/schemas/MarketplacePlugin'
      required:
        - kind
        - marketplace
        - plugin
        - not_loaded_by
      type: object
    IntegrationSearchDirectorySource:
      additionalProperties: false
      properties:
        kind:
          enum:
            - directory
          type: string
        status:
          $ref: '#/components/schemas/IntegrationSearchDirectoryStatus'
      required:
        - kind
        - status
      type: object
    IntegrationSearchMarketplaceSource:
      additionalProperties: false
      properties:
        kind:
          enum:
            - marketplace
          type: string
        marketplace:
          $ref: '#/components/schemas/PluginMarketplace'
        status:
          $ref: '#/components/schemas/IntegrationSearchMarketplaceStatus'
      required:
        - kind
        - marketplace
        - status
      type: object
    IntegrationSearchInstalled:
      additionalProperties: false
      properties:
        id:
          description: The plugin's id, or the MCP server's.
          format: uuid
          type: string
        kind:
          enum:
            - plugin
            - mcp_server
          type: string
      required:
        - kind
        - id
      type: object
    IntegrationSearchAetherIntegration:
      additionalProperties: false
      properties:
        aliases:
          description: Other words it is searched by, lowercase.
          items:
            type: string
          type: array
        category:
          description: The directory's category the gallery shows it under.
          enum:
            - source_control
            - issue_tracking
            - documents
            - design
            - chat
            - crm
            - database
            - hosting
            - ci
            - observability
            - analytics
            - payments
            - email
            - knowledge
          type: string
        default_credential_policy:
          enum:
            - creator
            - org
          type:
            - string
            - 'null'
        description:
          type: string
        display_name:
          type: string
        key:
          description: The server's key in the catalog.
          type: string
        url:
          type: string
      required:
        - key
        - display_name
        - description
        - category
        - aliases
        - url
        - default_credential_policy
      type: object
    DirectoryIntegration:
      additionalProperties: false
      properties:
        added_on:
          description: The day the integration joined the directory, YYYY-MM-DD.
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          type: string
        aliases:
          description: Other words the integration is searched by, lowercase.
          items:
            type: string
          type: array
        category:
          enum:
            - source_control
            - issue_tracking
            - documents
            - design
            - chat
            - crm
            - database
            - hosting
            - ci
            - observability
            - analytics
            - payments
            - email
            - knowledge
          type: string
        default_credential_policy:
          enum:
            - creator
            - org
          type:
            - string
            - 'null'
        description:
          type: string
        display_name:
          type: string
        featured_rank:
          description: >-
            Where the directory features the integration among its popular ones,
            1 first, no two integrations the same; null for one it does not
            feature.
          format: int64
          minimum: 1
          type:
            - integer
            - 'null'
        homepage:
          type: string
        installs_as:
          description: >-
            server: the integration is its MCP server alone, added to the
            catalog. plugin: a plugin bundling its MCP servers and its skills.
          enum:
            - server
            - plugin
          type: string
        key:
          description: >-
            The integration's name in the directory, and the key of its MCP
            server; installed as a plugin, the plugin's name.
          type: string
        skill_count:
          description: >-
            How many skills installing it bundles, as its source held them when
            Aether last checked the directory; 0 for one installed as its MCP
            server alone.
          format: int64
          minimum: 0
          type: integer
        source:
          discriminator:
            mapping:
              definition: '#/components/schemas/DirectoryDefinitionSource'
              marketplace: '#/components/schemas/DirectoryMarketplaceSource'
            propertyName: kind
          oneOf:
            - $ref: '#/components/schemas/DirectoryMarketplaceSource'
            - $ref: '#/components/schemas/DirectoryDefinitionSource'
      required:
        - key
        - display_name
        - description
        - homepage
        - category
        - aliases
        - default_credential_policy
        - installs_as
        - skill_count
        - featured_rank
        - added_on
        - source
      type: object
    PluginMarketplace:
      additionalProperties: false
      properties:
        display_name:
          type: string
        name:
          type: string
        url:
          type: string
      required:
        - name
        - display_name
        - url
      type: object
    IntegrationSearchRefusal:
      additionalProperties: false
      properties:
        agent:
          enum:
            - claude_code
            - codex
          type: string
        reason:
          description: 'codex_plugin_name: its name ends in ''.'', which Codex does not load.'
          enum:
            - codex_plugin_name
          type: string
      required:
        - agent
        - reason
      type: object
    MarketplacePlugin:
      additionalProperties: false
      properties:
        category:
          type: string
        description:
          type: string
        name:
          type: string
        unsupported_reason:
          type:
            - string
            - 'null'
      required:
        - name
        - description
        - category
        - unsupported_reason
      type: object
    IntegrationSearchDirectoryStatus:
      additionalProperties: false
      properties:
        state:
          enum:
            - available
          type: string
      required:
        - state
      type: object
    IntegrationSearchMarketplaceStatus:
      discriminator:
        mapping:
          available: '#/components/schemas/IntegrationSearchMarketplaceRead'
          unavailable: '#/components/schemas/IntegrationSearchMarketplaceUnavailable'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/IntegrationSearchMarketplaceRead'
        - $ref: '#/components/schemas/IntegrationSearchMarketplaceUnavailable'
    DirectoryDefinitionSource:
      additionalProperties: false
      properties:
        kind:
          enum:
            - definition
          type: string
        servers:
          items:
            $ref: '#/components/schemas/DirectoryDefinitionServer'
          minItems: 1
          type: array
        skills:
          $ref: '#/components/schemas/DirectorySkillsSource'
      required:
        - kind
        - servers
      type: object
    DirectoryMarketplaceSource:
      additionalProperties: false
      properties:
        kind:
          enum:
            - marketplace
          type: string
        marketplace_url:
          type: string
        plugin:
          description: >-
            The name the marketplace lists the plugin under: the integration's
            key.
          type: string
      required:
        - kind
        - marketplace_url
        - plugin
      type: object
    IntegrationSearchMarketplaceRead:
      additionalProperties: false
      properties:
        commit:
          description: >-
            The commit of the marketplace's default branch the listing was read
            at.
          type: string
        read_at:
          description: >-
            When Aether read the listing; searches use it until it is ten
            minutes old, then read the marketplace again.
          format: date-time
          type: string
        state:
          enum:
            - available
          type: string
      required:
        - state
        - commit
        - read_at
      type: object
    IntegrationSearchMarketplaceUnavailable:
      additionalProperties: false
      properties:
        checked_at:
          description: >-
            When Aether last tried to read it; searches report it unavailable
            for a minute after, then try again.
          format: date-time
          type: string
        detail:
          description: What went wrong, safe to show an admin.
          type: string
        failure:
          description: >-
            Why it could not be read, as installing from it would be refused
            (plugin_source_<failure>).
          enum:
            - address_refused
            - not_public
            - unreachable
            - not_found
            - unsupported
            - too_large
            - invalid
          type: string
        state:
          enum:
            - unavailable
          type: string
      required:
        - state
        - failure
        - detail
        - checked_at
      type: object
    DirectoryDefinitionServer:
      additionalProperties: false
      properties:
        key:
          type: string
        url:
          type: string
      required:
        - key
        - url
      type: object
    DirectorySkillsSource:
      additionalProperties: false
      properties:
        path:
          description: The directory holding the skills; empty for the repository's root.
          type: string
        ref:
          description: The branch or tag followed; null for the default branch.
          type:
            - string
            - 'null'
        repository_url:
          type: string
      required:
        - repository_url
        - path
        - ref
      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.