# Discovery (https://developer.godaddy.com/en/docs/references/rest/domains/v3/discovery) *** title: Discovery description: > Indicative, non-committing operations for finding and checking domains. Use suggestDomains for natural-language queries and getDomainAvailability for specific domain verification. Both return indicative pricing; locked pricing is established only at quote time. The check-availability controller carries no persistent identity. full: true \_openapi: toc: * depth: 2 title: Suggest available domains for a query url: '#suggest-available-domains-for-a-query' * depth: 2 title: Check availability of a single domain url: '#check-availability-of-a-single-domain' structuredData: headings: * content: Suggest available domains for a query id: suggest-available-domains-for-a-query * content: Check availability of a single domain id: check-availability-of-a-single-domain contents: * content: | Returns available domain name suggestions for a natural-language query or keyword set. All results are available (available-only contract). Prices are indicative; the authoritative price and availability check is at quote time. heading: suggest-available-domains-for-a-query * content: > Returns an indicative availability result for one domain, including per-term pricing when available. Availability is best-effort; the authoritative check is performed at quote time. This operation does not persist the check — there is no check identity or poll URL. A domain that cannot be checked is still returned as a `200` with an `error` object on the body; request-level failures use the `4xx` responses. heading: check-availability-of-a-single-domain *** ## GET /suggestions Suggest available domains for a query Returns available domain name suggestions for a natural-language query or keyword set. All results are available (available-only contract). Prices are indicative; the authoritative price and availability check is at quote time. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `query` | string | no | Natural-language query or keywords describing the desired domain, e.g. "sunrise bakery". Used to generate creative and keyword-spin suggestions. | | `tlds` | array | no | Top-level domains to be included in suggestions. | | `lengthMax` | integer | no | Maximum length of second-level domain. | | `lengthMin` | integer | no | Minimum length of second-level domain. | | `pageSize` | integer | no | Maximum number of suggestions in the response. Defaults to 10 when omitted. | | `sources` | array | no | Suggestion source strategies to activate. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Suggested available domains sorted by relevance. Content-Type: `application/json` Schema: - object - `items` (required): array — Available domain suggestions, sorted by relevance. All items are available by contract. - items: - `domain` (required): string — The suggested domain name in punycode A-label form. - `prices`: array — Multi-term pricing for this suggestion. Each entry represents a different registration period. Indicative only — the locked price is established at quote time. - items: - `term` (required): allOf(string & unknown) - `period` (required): integer — Number of term units for this pricing entry. - `price` (required): allOf(object & unknown) - `renewalPrice`: allOf(object & unknown) - `inventory`: allOf(string & unknown) **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **Security:** requires `bearerAuth`. ## GET /check-availability Check availability of a single domain Returns an indicative availability result for one domain, including per-term pricing when available. Availability is best-effort; the authoritative check is performed at quote time. This operation does not persist the check — there is no check identity or poll URL. A domain that cannot be checked is still returned as a `200` with an `error` object on the body; request-level failures use the `4xx` responses. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | The domain name to check, in punycode A-label form for IDNs. | | `optimizeFor` | allOf(string) | no | Optional. When omitted, defaults to SPEED. Availability is always re-verified authoritatively at quote time regardless of this setting. | | `iscCode` | string | no | ISC (International Shopper Code) for pricing context. When provided, prices reflect the applicable rates for this ISC. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Availability result for the requested domain. Content-Type: `application/json` ```json { "domain": "coffee24x7x365.com", "available": true, "definitive": false, "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 } }, { "term": "YEAR", "period": 3, "price": { "currencyCode": "USD", "value": 4599 }, "renewalPrice": { "currencyCode": "USD", "value": 6897 } }, { "term": "YEAR", "period": 5, "price": { "currencyCode": "USD", "value": 9197 }, "renewalPrice": { "currencyCode": "USD", "value": 11495 } } ] } ``` Schema: - object — The availability check result for a single requested domain. A checkable domain returns the available flag plus optional pricing. A domain that could not be checked carries an error object and no availability fields. Exactly one of available or error is present per item. - `domain` (required): string — The domain name checked, normalized to punycode A-label form. - `unicodeDomain`: string — The Unicode (U-label) form of the domain. Present only for IDN domains. - `available`: boolean — Whether this domain appears to be available for registration. Best-effort; re-verified at quote time. Present only when the domain was successfully checked (no error). - `definitive`: boolean — When true, the availability result was confirmed directly with the registry (ACCURACY mode). When false, the result is from a cached zone data check (SPEED mode) and may be stale. - `inventory`: allOf(string & unknown) - `prices`: array — Multi-term pricing for this domain. Each entry represents a different registration period (e.g. 1 year, 2 years). Present when available is true. - items: - `term` (required): allOf(string & unknown) - `period` (required): integer — Number of term units for this pricing entry. - `price` (required): allOf(object & unknown) - `renewalPrice`: allOf(object & unknown) - `error`: allOf(object & unknown) **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, or non-renewable domain status. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - object — The error information. - `name` (required): string — The human-readable, unique name of the error. - `correlationId` (required): string — Internal identifier used for correlation purposes. - `message` (required): string — The message that describes the error. - `informationLink`: string — The URI for detailed information related to this error for the developer. - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors. - items: - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors. - `value`: string — The value of the field that caused the error. - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`. - `issue` (required): string — The unique fine-grained application-level error code. - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value. - `links`: array — An array of error-related HATEOAS links. - items: - `href` (required): string — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `title`: string — The link title. - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target. - `targetSchema`: unknown — The schema that describes the link target. - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`. - `submissionMediaType`: string — The media type with which to submit data with the request. - `submissionSchema`: unknown — The schema that describes the request data. **Security:** requires `bearerAuth`.