# Create a custom hostname

Creates a custom hostname in your organization by specifying a hostname, a defaultSiteId, and a defaultContextId. Wildcards and apex domains are not currently supported for naming hostnames.

The number of custom hostnames you can create is limited by your organization's XM Cloud account entitlement. If this limit is exceeded, an error message is returned, and the custom hostname won't be created.

After it is created, the custom hostname details are stored and used to resolve and route traffic for incoming requests.

Endpoint: POST /api/admin/v1/hostnames
Version: 1.0
Security: BearerAuth

## Request fields (application/json):

  - `hostname` (string, required)
    The unique name assigned to a custom hostname.
    Example: "sitecore-api-preview.example.com"

  - `defaultSiteId` (string)
    The default [site ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html) associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is [resolved correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
    Example: "playsummit"

  - `defaultContextId` (string)
    The default [context ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html) associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is [resolved correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
    Example: "3BTl4aU7w12A5M76m9p8IA"

## Response 202 fields (application/json):

  - `id` (string, required)
    The custom hostname's unique identifier generated during creation.
    Example: "08de73f4-6f01-49b2-9ca6-d7fab7de966d"

  - `hostname` (string, required)
    The unique name assigned to a custom hostname.
    Example: "sitecore-api-preview.example.com"

  - `ssl` (object, required)
    The custom hostname's SSL properties, such as the domain control validation method, validation status, and related DNS records.

  - `ssl.expires_on` (string, required)
    The SSL certificate's expiration date and time.
    Example: "2021-02-06T18:11:23.531995Z"

  - `ssl.method` (string, required)
    The validation method used to verify the SSL certificate. 

Example values: "txt", "html"
    Example: "txt"

  - `ssl.status` (string, required)
    The current status of the SSL certificate.

Example values: "pending_validation", "active".
    Example: "active"

  - `ssl.validation_records` (array, required)
    The TXT records used for domain control validation (DCV).

  - `ssl.validation_records.txt_name` (string)
    The name of the TXT record used for DCV.

When adding this name to your DNS provider for DCV, you must exclude the domain name. For example, the TXT record name must be _acme_challenge.
    Example: "_acme_challenge.sitecore-api-preview.example.com"

  - `ssl.validation_records.txt_value` (string)
    The value of the TXT record used for DCV.
    Example: "9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c"

  - `ssl.validation_errors` (array, required)
    Errors encountered during domain control validation.

  - `ssl.validation_errors.message` (string)
    The error description.
    Example: "SERVFAIL looking up CAA for app.example.com"

  - `defaultSiteId` (string)
    The default [site ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html) associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is [resolved correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
    Example: "playsummit"

  - `defaultContextId` (string)
    The default [context ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html) associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is [resolved correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
    Example: "3BTl4aU7w12A5M76m9p8IA"

  - `ownership_verification` (object)
    The DNS records required to verify ownership of the custom hostname.

  - `ownership_verification.name` (string, required)
    The DNS name required to verify ownership of the custom hostname.

When adding this name to your DNS provider to verify ownership of the custom hostname, you must exclude the domain name. For example, the DNS name must be _cf_custom-hostname.
    Example: "_cf_custom-hostname.sitecore-api-preview.example.com"

  - `ownership_verification.type` (string, required)
    The DNS record type required to verify ownership of the custom hostname.
    Example: "txt"

  - `ownership_verification.value` (string, required)
    The DNS record value required to verify ownership of the custom hostname.
    Example: "e5e19fb0-0666-449d-a5ae-414f485dc63b"

  - `created_at` (string)
    The date and time the custom hostname was created.
    Example: "2021-02-06T18:11:23.531995Z"

  - `status` (string)
    The current status of the custom hostname.

Example values: "pending", "active".
    Example: "active"

  - `verification_errors` (array)
    A list of errors that occurred while verifying the ownership of the custom hostname.
    Example: ["SERVFAIL looking up CAA for app.example.com"]

## Response 400 fields (application/json):

  - `status` (integer, required)
    The HTTP response status code.
    Example: 400

  - `title` (string, required)
    The error description.
    Example: "BAD REQUEST"

  - `detail` (string, required)
    The error details.
    Example: "URL format is invalid"

  - `type` (string, required)
    URL to get more information about the error.
    Example: "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1"

  - `instance` (string, required)
    The instance where the error was encountered.
    Example: "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames"

## Response 401 fields (application/json):

  - `status` (integer, required)
    The HTTP response status code.
    Example: 401

  - `title` (string, required)
    The error description.
    Example: "UNAUTHORIZED"

  - `detail` (string, required)
    The error details.
    Example: "Authentication credentials are required to access the resource. All requests must be authenticated."

  - `type` (string, required)
    URL to get more information about the error.
    Example: "https://datatracker.ietf.org/doc/html/rfc7235#section-3.1"

  - `instance` (string, required)
    The instance where the error was encountered.
    Example: "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames"

## Response 403 fields (application/json):

  - `status` (integer, required)
    The HTTP response status code.
    Example: 403

  - `title` (string, required)
    The error description.
    Example: "FORBIDDEN"

  - `detail` (string, required)
    The error details.
    Example: "No access to the requested resource"

  - `type` (string, required)
    URL to get more information about the error.
    Example: "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3"

  - `instance` (string, required)
    The instance where the error was encountered.
    Example: "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames"

## Response 409 fields (application/json):

  - `status` (integer, required)
    The HTTP response status code.
    Example: 409

  - `title` (string, required)
    The error description.
    Example: "CONFLICT"

  - `detail` (string, required)
    The error details.
    Example: "The custom hostname already exists."

  - `type` (string, required)
    URL to get more information about the error.
    Example: "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8"

  - `instance` (string, required)
    The instance where the error was encountered.
    Example: "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames"

## Response 422 fields (application/json):

  - `status` (integer, required)
    The HTTP response status code.
    Example: 422

  - `title` (string, required)
    The error description.
    Example: "UNPROCESSABLE ENTITY"

  - `detail` (string, required)
    The error details.
    Example: "The maximum number of custom hostnames has been reached."

  - `type` (string, required)
    URL to get more information about the error.
    Example: "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1"

  - `instance` (string, required)
    The instance where the error was encountered.
    Example: "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames"

## Response 500 fields (application/json):

  - `status` (integer, required)
    The HTTP response status code.
    Example: 500

  - `title` (string, required)
    The error description.
    Example: "INTERNAL SERVER ERROR"

  - `detail` (string, required)
    The error details.
    Example: "The server was unable to complete your request. Please try again later."

  - `type` (string, required)
    URL to get more information about the error.
    Example: "https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1"

  - `instance` (string, required)
    The instance where the error was encountered.
    Example: "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames"