> ## Documentation Index
> Fetch the complete documentation index at: https://docs.namify.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# MetaSearch

> Search a name and return the best available domains: the exact match, available alternatives, and optional AI-generated suggestions, each with live pricing.

Returns a ranked set of available domains for a search term: the exact-match domain, available alternatives, and (optionally) AI-generated brandable suggestions, each with ready-to-display pricing.

**How it works:** Pass a `search_term`: either a bare name (`coffee`) or a full domain including a TLD (`coffee.com`). The response leads with a featured result (`type: "hero"`), followed by the results list, and (when enabled) a trailing block of AI-suggested names. Every item carries a live `available` flag and a `pricing` object (`null` when the domain is taken).

**Suggestions:** Set `autosuggest=true` and MetaSearch automatically suggests additional available names (close variations around your search term) in the results list. Set `aisuggest=true` and it appends a block of AI-suggested, brandable names (each `type: "ai_suggestion"`). Both are off by default; enable either or both.

**Pricing:** Each available result includes a `pricing` object with the registration and renewal price, an `is_free_first_year` flag, and a ready-to-display `summary` string (e.g. `"1st Year Free, then $9.99/yr"`). Prices are scoped to your partner account's catalogue.

**The searched domain:** When the search includes a TLD (e.g. `coffee.com`), the row matching that exact domain is flagged with `is_searched_exact: true`, so you can highlight "the domain you searched," whether it's available or taken.


## OpenAPI

````yaml api-reference/metasearch-openapi.json GET /v1/search
openapi: 3.1.0
info:
  title: Namify MetaSearch API
  description: >-
    MetaSearch returns a ranked set of available domains for a search term: the
    exact match, available alternatives, and optional AI-generated suggestions,
    each with live pricing.


    All requests require a bearer token issued for your partner account. Results
    (TLDs and pricing) are scoped to your account's configured catalogue.


    **Base URL:** `https://metasearch.namify.host`
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://metasearch.namify.host
security:
  - bearerAuth: []
paths:
  /v1/search:
    get:
      tags:
        - Domains
      summary: MetaSearch domain search
      description: >-
        MetaSearch takes a search term and returns a ranked set of domains: the
        exact match, plus available alternatives (when `autosuggest` is on) and
        AI-suggested brandable names (when `aisuggest` is on), each with live
        pricing. The response leads with a featured result (`type: "hero"`),
        then the results list, then any AI-suggested names.
      parameters:
        - name: search_term
          in: query
          required: true
          description: >-
            The name to search: either a bare label (`coffee`) or a full domain
            including a TLD (`coffee.com`). Include a TLD to search that exact
            domain; the matching row is returned flagged `is_searched_exact:
            true`. Maximum 63 characters.
          schema:
            type: string
            example: coffee
        - name: autosuggest
          in: query
          required: false
          description: >-
            When `true`, MetaSearch automatically suggests additional available
            names (close variations coined around your `search_term`) and folds
            them into the results list alongside the exact match. Defaults to
            `false`.
          schema:
            type: boolean
            default: false
            example: true
        - name: aisuggest
          in: query
          required: false
          description: >-
            When `true`, MetaSearch appends a block of AI-suggested names:
            brandable, model-coined alternatives to your `search_term`, each
            returned with `type: "ai_suggestion"`. Independent of `autosuggest`;
            defaults to `false`.
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: Ranked search results with live availability and pricing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                results:
                  - domain_name: mycafe.store
                    sld: mycafe
                    tld: store
                    available: true
                    type: hero
                    is_searched_exact: false
                    pricing:
                      currency: USD
                      register: 0
                      renew: 9.99
                      period: year
                      is_free_first_year: true
                      summary: 1st Year Free, then $9.99/yr
                  - domain_name: mycafe.com
                    sld: mycafe
                    tld: com
                    available: true
                    type: result
                    is_searched_exact: false
                    pricing:
                      currency: USD
                      register: 12.99
                      renew: 14.99
                      period: year
                      is_free_first_year: false
                      summary: $12.99/yr
                  - domain_name: mycafehq.store
                    sld: mycafehq
                    tld: store
                    available: true
                    type: ai_suggestion
                    is_searched_exact: false
                    pricing:
                      currency: USD
                      register: 0
                      renew: 9.99
                      period: year
                      is_free_first_year: true
                      summary: 1st Year Free, then $9.99/yr
                results_total: 8
                results_hidden: 0
                meta:
                  search_term: mycafe
                  typed_tld: null
                  autosuggest: true
                  aisuggest: true
        '400':
          description: '`search_term` is missing, empty, or longer than 63 characters.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '401':
          description: API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorServer'
        '503':
          description: The domain availability service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnavailable'
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        results:
          type: array
          description: >-
            The full result set, in render order: the `hero` first (when
            present), then the results list, then any AI-suggested names. Never
            paginated.
          items:
            $ref: '#/components/schemas/DomainResult'
        results_total:
          type: integer
          description: Total number of results-list items.
        results_hidden:
          type: integer
          description: >-
            Results-list items beyond the first 10 (use to drive a "show more"
            affordance).
        message:
          type: string
          description: >-
            Present only when there are no results (e.g. "No results for this
            name").
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorBadRequest:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: search_term is required and must not be empty after sanitisation
    ErrorUnauthorized:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Invalid partner token
    ErrorServer:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Internal server error
    ErrorUnavailable:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Domain availability service unavailable
    DomainResult:
      type: object
      properties:
        domain_name:
          type: string
          description: The full domain name (SLD + TLD), e.g. `coffee.com`.
        sld:
          type: string
          description: >-
            The second-level domain: the name portion, left of the dot (e.g.
            `coffee` in `coffee.com`).
        tld:
          type: string
          description: >-
            The top-level domain: the extension, without the leading dot (e.g.
            `com`).
        available:
          type: boolean
          description: >-
            Whether the domain is available to register through your partner
            account. Taken names can still appear (e.g. the searched exact) with
            `available: false` and `pricing: null`.
        type:
          type: string
          enum:
            - hero
            - result
            - ai_suggestion
          description: >-
            What kind of result this is. `hero`: the featured pick MetaSearch
            leads with; `result`: a standard results-list entry (an exact match,
            or an automatically suggested name when `autosuggest` is on);
            `ai_suggestion`: an AI-suggested, model-coined name (returned when
            `aisuggest` is on).
        is_searched_exact:
          type: boolean
          description: >-
            `true` only for the row matching the exact domain in the
            `search_term` (when a TLD was included, e.g. `coffee.com`). Use it
            to highlight "the domain you searched," whether available or taken.
            `false` on every other row.
        pricing:
          description: >-
            Pricing for the domain, from your account's catalogue. `null` when
            the domain is unavailable.
          oneOf:
            - $ref: '#/components/schemas/Pricing'
            - type: 'null'
    Meta:
      type: object
      properties:
        search_term:
          type: string
          description: Your `search_term`, normalised (lowercased and trimmed).
        typed_tld:
          type:
            - string
            - 'null'
          description: >-
            The TLD parsed from the `search_term` when a full domain was
            searched (e.g. `com` for `coffee.com`), otherwise `null`.
        autosuggest:
          type: boolean
          description: The resolved value of the `autosuggest` flag for this request.
        aisuggest:
          type: boolean
          description: The resolved value of the `aisuggest` flag for this request.
    Pricing:
      type: object
      properties:
        currency:
          type: string
          description: ISO 4217 currency code (e.g. "USD").
        register:
          type: number
          description: >-
            First-year registration price. `0` means the first year is free (see
            `is_free_first_year`).
        renew:
          type: number
          description: Standard annual renewal price, charged from the second year onward.
        period:
          type: string
          description: Billing period the amounts apply to (always "year").
        is_free_first_year:
          type: boolean
          description: >-
            `true` when the first year is free (`register` is `0`); the customer
            pays `renew` from year two.
        summary:
          type: string
          description: >-
            A ready-to-display price string you can render as-is (e.g. "1st Year
            Free, then $9.99/yr" or "$12.99/yr").
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your partner API key. Include it in the Authorization header as `Bearer
        <token>`. Unauthenticated requests return 401 Unauthorized.

````