Just Domain Search API

openapi: 3.2.0
info:
  title: just-domain-mcp Search API
  version: 0.1.0
tags:
- name: Search
paths:
  /api/v1/search:
    get:
      summary: Get Search
      operationId: get_search_api_v1_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 512
          description: 'Search query: a bare label (''acme''), a single FQDN (''acme.io''), or a comma-separated mix (''acme.com, acme.io, brand''). Bare labels fan out to the featured TLDs.'
          title: Q
        description: 'Search query: a bare label (''acme''), a single FQDN (''acme.io''), or a comma-separated mix (''acme.com, acme.io, brand''). Bare labels fan out to the featured TLDs.'
      - name: tlds
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          description: Optional comma-separated TLD list to fan a bare label out to (e.g. 'com,io,ai'). Ignored for terms that already include a TLD. Defaults to the configured featured TLDs.
          title: Tlds
        description: Optional comma-separated TLD list to fan a bare label out to (e.g. 'com,io,ai'). Ignored for terms that already include a TLD. Defaults to the configured featured TLDs.
      - name: fresh
        in: query
        required: false
        schema:
          type: boolean
          description: Ask the registrar now instead of reusing a recent answer. Without it a result may be reused for up to 10 minutes (an available name) or a day (a taken one). The checkout page sets it.
          default: false
          title: Fresh
        description: Ask the registrar now instead of reusing a recent answer. Without it a result may be reused for up to 10 minutes (an available name) or a day (a taken one). The checkout page sets it.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Search
components:
  schemas:
    Price:
      properties:
        amount_minor:
          type: integer
          title: Amount Minor
          description: Amount in the smallest currency unit (e.g. cents).
        currency:
          type: string
          maxLength: 3
          minLength: 3
          title: Currency
          description: ISO-4217 currency code.
        formatted:
          type: string
          title: Formatted
          description: Human-readable price, e.g. '$12.99'.
      type: object
      required:
      - amount_minor
      - currency
      - formatted
      title: Price
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DomainResult:
      properties:
        fqdn:
          type: string
          title: Fqdn
        name:
          type: string
          title: Name
        tld:
          type: string
          title: Tld
        available:
          type: boolean
          title: Available
        status:
          type: string
          title: Status
          description: Raw provider status, e.g. 'free', 'active', 'premium'.
        premium:
          type: boolean
          title: Premium
          default: false
        price:
          anyOf:
          - $ref: '#/components/schemas/Price'
          - type: 'null'
          description: 'Registration price: the total for ONE full registration term of this ending, not a per-year rate. One year on most endings; two years on .ai, whose registry mandates a two-year term.'
        renewal_price:
          anyOf:
          - $ref: '#/components/schemas/Price'
          - type: 'null'
          description: 'Renewal price: the total for ONE further registration term, on the same basis as `price`. What a later term would cost at today''s rate, not a figure anyone has been charged or quoted for a specific renewal. An owner renews, and turns auto-renew on or off, on their own dashboard at https://justdomain.ai/dashboard, which is the only authoritative source for one domain''s renewal state.'
        term_years:
          type: integer
          title: Term Years
          description: Length in years of ONE registration term for this ending, and therefore the period `price` and `renewal_price` each cover. 1 on most endings; 2 on .ai, whose registry mandates a two-year term with no one-year option. Read this before describing any price as annual.
          default: 1
        requires_additional_data:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Additional Data
          description: 'Does this ending''s registry demand registrant data beyond standard contact details - a nexus declaration, a national ID, a professional credential? TRI-STATE: true / false / null = we do not know. Just Domain cannot collect or submit that data yet, so a true (or unknown) value means the name is reported honestly but carries no `checkout_url`.'
        checkout_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Checkout Url
          description: URL on the Just Domain website where the user completes payment. Set for available domains we can actually register; null for unavailable ones, for premium names (the checkout API refuses them), and for endings whose registry requires registrant data we cannot supply yet. The MCP tool handler fills this in after the bare service call so the UI widget's Buy button can open checkout directly in one click.
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      type: object
      required:
      - fqdn
      - name
      - tld
      - available
      - status
      title: DomainResult
    SearchResponse:
      properties:
        domains:
          items:
            type: string
          type: array
          title: Domains
          description: The exact domains requested by the caller, echoed back.
        results:
          items:
            $ref: '#/components/schemas/DomainResult'
          type: array
          title: Results
        alternatives:
          items:
            $ref: '#/components/schemas/DomainResult'
          type: array
          title: Alternatives
          description: 'Available domains the caller did not ask about, offered only when every requested domain came back unavailable. Same label the caller typed, on a different ending; nothing is invented and nothing here duplicates a name in `results`. Every entry is available, non-premium and carries a `checkout_url`, so it can be offered to the user directly. Empty is not an error. It means one of three things: recovery is switched off for this deployment, or the search was not a dead end, or the same label is taken on the other endings too, which is the normal outcome for a common dictionary word. Do not tell the user that other endings were checked unless this list is non-empty. Do not re-check these; they were checked live in this same call.'
        component_hint:
          type: string
          const: domain_search_results
          title: Component Hint
          default: domain_search_results
        next_action:
          type: string
          title: Next Action
          description: An instruction for the assistant reading this response, or the string 'none' when there is nothing extra to do. It is set in two cases. When no requested domain and no alternative in this response can be registered through Just Domain, it tells you how to search again. When at least one domain carries a `checkout_url`, it tells you to make the name of each such domain you mention in your reply a clickable link to its `checkout_url`. When it is not 'none', carry it out in this same turn before or while replying to the user; it is written to be executable as-is.
          default: none
        warnings:
          items:
            type: string
          type: array
          title: Warnings
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Set when the search could not be completed (e.g. invalid query, provider failure).
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
      type: object
      required:
      - domains
      - results
      title: SearchResponse