---
title: "Search domain names with the operator in a conversation"
method: POST
path: "/v1/domains/search"
tags: ["Domains"]
---

# Search domain names with the operator in a conversation

`POST /v1/domains/search`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/domains/search`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-better-auth.session_token`
  - none

Find domain names with the dashboard's search workflow. A single keyword returns exact domain matches and domain hacks. A naming brief generates suggestions. Each search checks availability and Jev scores. The workflow replaces unavailable generated names. Refine the search with messages, likes, dislikes and selections. Carry the returned session unchanged into the next call. Use stable suggestion IDs for feedback. Display prices include the same fees as the dashboard. If complete is false, inspect problems. To resume, send the returned session without a new message. Confirm availability again before registration.

## Request body

- object
  - `teamId` string
  - `message` string: The operator's naming brief or follow-up. Omit to apply feedback or resume incomplete work.
  - `session` object: Carry the complete returned session unchanged between turns.
    - `version` 1, required
    - `teamId` string
    - `messages` object[], required
      - `role` 'user' | 'assistant', required
      - `content` string, required
      - `local` boolean
      - `kind` 'feedback'
    - `suggestions` object[], required
      - `domain` string, required
      - `reason` string, required
      - `score` number, required
      - `id` string, required
      - `number` integer, required
      - `selected` boolean, required
      - `taste` 'neutral' | 'liked' | 'disliked', required
      - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
      - `sellable` boolean
      - `jev` object
        - `score` number, required
        - `confidence` number, required
      - `retired` boolean
      - `source` 'instant'
      - `hideDescription` boolean
      - `checkedAt` string, date-time
      - `availabilitySource` 'dsapi' | 'rdap' | 'local'
      - `price` object, nullable
        - `amount` number, required
        - `formatted` string, required
        - `currency` string, required
      - `ranking` 'pending' | 'scoring' | 'scored' | 'error', required
    - `pending` object
      - `body` object, required: The unchanged input for a generation pass that has not completed.
        - `teamId` string
        - `phase` 'initial' | 'enrichment' | 'refinement' | 'replacement', required
        - `automatic` boolean
        - `poolPolicy` 'ranked-available': Request ranked available pools. Omit this field to keep neutral replacement limits.
        - `messages` object[], required
          - `role` 'user' | 'assistant', required
          - `content` string, required
        - `suggestions` object[], required
          - `domain` string, required
          - `reason` string, required
          - `score` number, required
          - `id` string, required
          - `number` integer, required
          - `selected` boolean, required
          - `taste` 'neutral' | 'liked' | 'disliked', required
          - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
          - `sellable` boolean
          - `jev` object
            - `score` number, required
            - `confidence` number, required
          - `retired` boolean
          - `source` 'instant'
          - `hideDescription` boolean
      - `acceptedIds` string[]: Suggestion IDs that this pass added. Other concurrent passes do not use its budget.
      - `baselineIds` string[], required: Suggestion IDs present before this pass, used to preserve its generation budget after retry.
      - `slots` string[], required: The original unavailable suggestion IDs that replacement may retire.
    - `replacement` object
      - `body` object, required: The unchanged input for a generation pass that has not completed.
        - `teamId` string
        - `phase` 'initial' | 'enrichment' | 'refinement' | 'replacement', required
        - `automatic` boolean
        - `poolPolicy` 'ranked-available': Request ranked available pools. Omit this field to keep neutral replacement limits.
        - `messages` object[], required
          - `role` 'user' | 'assistant', required
          - `content` string, required
        - `suggestions` object[], required
          - `domain` string, required
          - `reason` string, required
          - `score` number, required
          - `id` string, required
          - `number` integer, required
          - `selected` boolean, required
          - `taste` 'neutral' | 'liked' | 'disliked', required
          - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
          - `sellable` boolean
          - `jev` object
            - `score` number, required
            - `confidence` number, required
          - `retired` boolean
          - `source` 'instant'
          - `hideDescription` boolean
      - `acceptedIds` string[]: Suggestion IDs that this pass added. Other concurrent passes do not use its budget.
      - `baselineIds` string[], required: Suggestion IDs present before this pass, used to preserve its generation budget after retry.
      - `slots` string[], required: The original unavailable suggestion IDs that replacement may retire.
  - `feedback` object[]
    - `id` string, required: Stable suggestion ID from the returned session; display reference numbers are only for people.
    - `taste` 'neutral' | 'liked' | 'disliked'
    - `selected` boolean

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `message` string, required
    - `session` object, required
      - `version` 1, required
      - `teamId` string
      - `messages` object[], required
        - `role` 'user' | 'assistant', required
        - `content` string, required
        - `local` boolean
        - `kind` 'feedback'
      - `suggestions` object[], required
        - `domain` string, required
        - `reason` string, required
        - `score` number, required
        - `id` string, required
        - `number` integer, required
        - `selected` boolean, required
        - `taste` 'neutral' | 'liked' | 'disliked', required
        - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
        - `sellable` boolean
        - `jev` object
          - `score` number, required
          - `confidence` number, required
        - `retired` boolean
        - `source` 'instant'
        - `hideDescription` boolean
        - `checkedAt` string, date-time
        - `availabilitySource` 'dsapi' | 'rdap' | 'local'
        - `price` object, nullable
          - `amount` number, required
          - `formatted` string, required
          - `currency` string, required
        - `ranking` 'pending' | 'scoring' | 'scored' | 'error', required
      - `pending` object
        - `body` object, required: The unchanged input for a generation pass that has not completed.
          - `teamId` string
          - `phase` 'initial' | 'enrichment' | 'refinement' | 'replacement', required
          - `automatic` boolean
          - `poolPolicy` 'ranked-available': Request ranked available pools. Omit this field to keep neutral replacement limits.
          - `messages` object[], required
            - `role` 'user' | 'assistant', required
            - `content` string, required
          - `suggestions` object[], required
            - `domain` string, required
            - `reason` string, required
            - `score` number, required
            - `id` string, required
            - `number` integer, required
            - `selected` boolean, required
            - `taste` 'neutral' | 'liked' | 'disliked', required
            - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
            - `sellable` boolean
            - `jev` object
              - …
            - `retired` boolean
            - `source` 'instant'
            - `hideDescription` boolean
        - `acceptedIds` string[]: Suggestion IDs that this pass added. Other concurrent passes do not use its budget.
        - `baselineIds` string[], required: Suggestion IDs present before this pass, used to preserve its generation budget after retry.
        - `slots` string[], required: The original unavailable suggestion IDs that replacement may retire.
      - `replacement` object
        - `body` object, required: The unchanged input for a generation pass that has not completed.
          - `teamId` string
          - `phase` 'initial' | 'enrichment' | 'refinement' | 'replacement', required
          - `automatic` boolean
          - `poolPolicy` 'ranked-available': Request ranked available pools. Omit this field to keep neutral replacement limits.
          - `messages` object[], required
            - `role` 'user' | 'assistant', required
            - `content` string, required
          - `suggestions` object[], required
            - `domain` string, required
            - `reason` string, required
            - `score` number, required
            - `id` string, required
            - `number` integer, required
            - `selected` boolean, required
            - `taste` 'neutral' | 'liked' | 'disliked', required
            - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
            - `sellable` boolean
            - `jev` object
              - …
            - `retired` boolean
            - `source` 'instant'
            - `hideDescription` boolean
        - `acceptedIds` string[]: Suggestion IDs that this pass added. Other concurrent passes do not use its budget.
        - `baselineIds` string[], required: Suggestion IDs present before this pass, used to preserve its generation budget after retry.
        - `slots` string[], required: The original unavailable suggestion IDs that replacement may retire.
    - `suggestions` object[], required
      - `domain` string, required
      - `reason` string, required
      - `score` number, required
      - `id` string, required
      - `number` integer, required
      - `selected` boolean, required
      - `taste` 'neutral' | 'liked' | 'disliked', required
      - `availability` 'unchecked' | 'checking' | 'unregistered' | 'registered' | 'unknown', required
      - `sellable` boolean
      - `jev` object
        - `score` number, required
        - `confidence` number, required
      - `retired` boolean
      - `source` 'instant'
      - `hideDescription` boolean
      - `checkedAt` string, date-time
      - `availabilitySource` 'dsapi' | 'rdap' | 'local'
      - `price` object, nullable
        - `amount` number, required
        - `formatted` string, required
        - `currency` string, required
      - `ranking` 'pending' | 'scoring' | 'scored' | 'error', required
      - `reference` integer, required: Current displayed row number. Use id for durable feedback.
      - `displayPrice` object, nullable, required: First-year price including fees, matching the dashboard; null when no quote exists.
        - `amount` number, required
        - `formatted` string, required
        - `currency` string, required
    - `topPick` string, nullable, required
    - `complete` boolean, required: False when a stage needs retry. Keep this session and inspect problems.
    - `problems` object[], required
      - `stage` 'generation' | 'ranking' | 'availability' | 'replacement', required
      - `code` string, required
      - `message` string, required
      - `retryAfterSeconds` number

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)