---
title: Domain Search with Suggestions API Reference
version: 1.0.0
description: Check domain availability and receive suggestions for related domains across all top-level domains (TLDs). Supports optional suggestion parameters including a boolean flag to enable suggestions and a count parameter to control the number of results. Uses DNS-based or WHOIS-based lookups to determine domain availability for each suggestion.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 4
---

## Table of Contents

- [Domain Search with Suggestions API Reference v1.0.0](#domain-search-with-suggestions-api-reference-v100)
  - [Authentication](#authentication)
  - [Domain APIs](#domain-apis)
    - [suggestDomainAvailability](#suggestdomainavailability)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [DomainAvailabilityResponse](#domainavailabilityresponse)
    - [DomainSuggestionResponse](#domainsuggestionresponse)
    - [DomainSuggestionItem](#domainsuggestionitem)
    - [ErrorResponse](#errorresponse)



# Domain Search with Suggestions API Reference v1.0.0

Check domain availability and receive suggestions for related domains across all top-level domains (TLDs). Supports optional suggestion parameters including a boolean flag to enable suggestions and a count parameter to control the number of results. Uses DNS-based or WHOIS-based lookups to determine domain availability for each suggestion.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Domain APIs

### suggestDomainAvailability

`GET /domain/availability/suggestions`

*Check domain availability and receive suggestions for related domains.*

The Domain Search API is designed to simplify the process of finding available domain names across all top-level domains (TLDs) and second-level domains (SLDs).

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response.|
|domain|query|string|true|Domain name for availability and suggestions.|
|source|query|string|false|Specify the data source for domain availability checks. Use "dns" for DNS-based lookups or "whois" for WHOIS-based lookups. By default, "dns" is used.|
|sug|query|boolean|false|Set to false to get a single availability result for exactly the given domain (same shape as the Domain Availability API), with no suggestions. Omitting this parameter, or setting it to true, returns an array of suggested alternate-TLD domains instead — despite the parameter's name, omitting it does not behave like false.|
|count|query|integer|false|Requested number of suggestions. Observed behavior: the API returns at least 5 alternate-TLD suggestions regardless of a lower count value; recognizable/brandable domains can return more than requested, drawn from a larger suggestion pool.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|
|source|dns|
|source|whois|

> Example responses

> Success. Shape depends on sug: false returns a single availability object; omitted or true returns an array of suggestions.

```json
{
  "domain_available_response": [
    {
      "domain": "acme.org",
      "domainAvailability": false
    },
    {
      "domain": "acme.dev",
      "domainAvailability": false
    },
    {
      "domain": "acme.net",
      "domainAvailability": false
    },
    {
      "domain": "acme.com",
      "domainAvailability": false
    },
    {
      "domain": "acme.info",
      "domainAvailability": false
    }
  ]
}
```

```json
{
  "domain": "quixoticbramble77.com",
  "domainAvailability": true
}
```

> Bad Request – Invalid domain parameter

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/domain/availability/suggestions",
  "status": 400,
  "timestamp": "2026-07-27T12:19:46.594Z"
}
```

> Request Timeout – Unable to fetch WHOIS data

```json
{
  "timestamp": "2025-08-14T10:37:21.871Z",
  "status": 408,
  "error": "Request Timeout",
  "message": "Unable to fetch whois data. Please try again. [For Technical Support email at: support@apifreaks.com]",
  "path": "/v1.0/domain/availability/suggestions"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success. Shape depends on sug: false returns a single availability object; omitted or true returns an array of suggestions.|Inline|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request – Invalid domain parameter|[ErrorResponse](#errorresponse)|
|408|[Request Timeout](https://tools.ietf.org/html/rfc7231#section-6.5.7)|Request Timeout – Unable to fetch WHOIS data|[ErrorResponse](#errorresponse)|

#### Response Schema

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|408|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### DomainAvailabilityResponse

Domain availability check response containing the domain name and availability status. Returned when sug=false.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|domain|string|true|none|Name of the queried domain.|
|domainAvailability|boolean|true|none|True if available, false if not available.|

### DomainSuggestionResponse

Domain suggestion response containing a list of availability-suggestions.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|domain_available_response|[[DomainSuggestionItem](#domainsuggestionitem)]|true|none|List of domain availability objects.|

### DomainSuggestionItem

A single domain suggestion with availability status.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|domain|string|true|none|Name of the suggested domain.|
|domainAvailability|boolean|true|none|True if available, false if not available.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|