---
title: "Domains"
method: POST
path: "/v1/domains"
tags: ["Suprsonic"]
---

# Domains

`POST /v1/domains`

## Request

- Base URL: `https://suprsonic.ai`
- URL: `https://suprsonic.ai/v1/domains`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/docs/v1/domains/post.ts> (a function with typed inputs; its response is checked against the schema)

Find domain names and the extensions that fit a business. Returns, by mode, name ideas with prices, extensions that fit with reasons, one name across extensions, availability for a list of domains, prices per extension, or the extension catalog. Use to name a business or check domains before buying one; it never registers or buys a domain. For facts about a domain that is already live use site-intel. mode decides which fields apply: company_name and description for the suggest modes, query for search-extensions, domains for check-availability, tlds for pricing. Cost: suggest-names 5 credits, suggest-extensions 3 credits, search-extensions 2 credits, check-availability 1 credit, pricing 1 credit, tlds 1 credit, charged only when a call succeeds.

## Request body

- DomainsRequest
  - `mode` string
  - `company_name` string, nullable
  - `description` string, nullable
  - `company_id` string, nullable
  - `purpose` string, nullable
  - `search_options` DomainSearchOptions: Search options, one vocabulary shared with the app (apps/shared/data/domain-search-options.json). Send only the fields you set; null (or priorities []) leaves that field to the brief.
    - `priorities` string[], nullable: Ordering objectives, most important first: total_length (Shortest domain); annual_price (Cheapest first year); renewal_price (Cheapest to keep); registration_total (Lowest upfront); semantic_fit (Best fit); brandability (Brandable); label_length (Shortest name)
    - `max_total_length` integer, nullable: Longest complete domain, dots and extension included
    - `max_label_length` integer, nullable: Longest name before the dot
    - `max_annual_price` number, nullable: Highest first-year price per year, in USD, at the cheaper registrar
    - `max_renewal_price` number, nullable: Highest yearly renewal price, in USD
    - `max_registration_total` number, nullable: Highest amount charged at purchase, in USD
    - `hacks` 'include' | 'exclude' | 'only', nullable: Domain hacks: include (Allowed); exclude (No hacks); only (Only hacks)
    - `allow_premium` boolean, nullable: Include registry premium names, which cost more than the standard price
  - `focus` string, nullable
  - `query` string, nullable
  - `exact_extension` boolean
  - `offset` integer
  - `tlds` string[], nullable
  - `domains` string[], nullable

## Response `200`

The call's envelope: success, data (the capability's result), metadata, and credits_used (0 when the call did not succeed).

- UnifiedResponse: Standard envelope for all unified API responses.
  - `success` boolean, required
  - `data` union
    - object
    - unknown[]
      - unknown
  - `error` UnifiedError: RFC 7807 problem detail for machine-actionable errors.
    - `type` string, required
    - `title` string, required
    - `status` integer, required
    - `detail` string, nullable
    - `is_retriable` boolean
    - `retry_after_seconds` integer, nullable
    - `alternative_action` string, nullable
    - `error_category` string
    - `caller_error` string, nullable
  - `metadata` UnifiedMetadata: Metadata included in every unified API response.
    - `provider_used` string, nullable
    - `providers_tried` string[]
    - `mode_used` string, nullable
    - `response_time_ms` integer
    - `request_id` string
    - `capability` string, nullable
    - `params` object, nullable
  - `credits_used` integer

## Other responses

- `401`: No API key, or one that was not found or is revoked.
- `402`: Not enough credits for this call. The error's alternative_action says where to add them.
- `403`: The account is restricted by a billing issue.
- `422`: Validation Error
- `429`: The key's rate limit is reached. The error's retry_after_seconds says when to try again.

## Changes

- **2026-11-01** `120f2dd4c855`: 7 info
  - added the optional property `detail/caller_error` to the response with the `401` status
  - added the optional property `detail/caller_error` to the response with the `402` status
  - added the optional property `detail/caller_error` to the response with the `403` status
  - added the optional property `detail/caller_error` to the response with the `429` status
  - …3 more
- **2026-10-23** `9edc3bfe1b9c`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-10-19** `8134f9a5b206`: 3 breaking, 23 info
  - the `search_options/anyOf[#/components/schemas/DomainSearchOptions -> subschema #1: DomainSearchOptions]/` request property type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - the `detail/items/` response's property type changed from no type to `object` for status `422`
  - api operation id `unified_domains_v1_domains_post` removed and replaced with `domains`
  - …22 more
- **2026-09-25** `fcd4ea70588a`: 1 info
  - added the new optional request property `search_options`
- **2026-08-29** `2e9e8abc82a5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/changes/v1/domains/post.md)

---

[API](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api.md) - [All operations](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/revisions/120f2dd4c855?raw)