Custom hostnames

Resolving a custom hostname during a request

When you create a custom hostname it's associated with either defaultContextId or defaultSiteId, or both. These IDs help determine access to specific applications supported by Sitecore. After your custom hostname is verified, it can be used to route traffic to the correct service based on its associated IDs.

Sitecore identifies the target service or application of your request, based on the hostname you use and whether you include the tenant name in the request URL. Here are the possible scenarios:

Note

A custom hostname can retrieve media from any tenant inside the organization if you include the tenant name in the request URL. For example https://customhostname.io/v1/media/edge/images/<tenantName>/media/banner-image.jpg.

If you don't specify the tenant name in the URL, then the associated Context ID is used to resolve the tenant. For example https://customhostname.io/v1/media/edge/images/banner-image.jpg.

Use a custom hostname without ContextId or SiteId

If you use a custom hostname in your request without explicitly including a ContextId in the query parameter or header, or a SiteId in the query parameter or body, the system automatically uses the defaultContextId or defaultSiteId linked to that custom hostname. This simplifies your requests because you don't have to manually include those IDs every time.

The system automatically uses the defaultContextId or defaultSiteId linked to the custom hostname, depending on the request type:
- defaultContextId is used to resolve tenant-specific requests, such as media requests made through /v1/media/edge/images/*.
- defaultSiteId is used to resolve site-specific requests, such as GraphQL requests made through /v1/content/api/graphql/v1.
Use a custom hostname with ContextId or SiteId

If you use a custom hostname along with a ContextId in the query parameter or header, or a SiteId in the query parameter or body, the system will prioritize these provided IDs over the default ones associated with the hostname.
Use the default hostname

If you use the default edge-platform.sitecorecloud.io hostname, there are no specific IDs automatically associated with it. To make sure your request reaches the correct destination, you need to include either the ContextId or SiteId in the request.

Custom hostname media item requests

Note

Custom hostnames can only be used with the live context ID and for media items published to Experience Edge.

Media requests made through a custom hostname are resolved at the environment level and do not use a site ID. For this reason, defaultSiteId has no effect on media item requests made through /v1/media/edge/images/*. The associated defaultContextId is used to resolve the environment when a environment name is not included in the URL.

To prevent search engines from indexing your media on the http://edge.sitecorecloud.io domain, Experience Edge media requests include the X-Robots-Tag:noindex header.

However, when requesting a media item from a custom hostname, you can use the relative path /v1/media/edge/images/ to have the X-Robots-Tag:noindex header omitted from the response. This lets search engines properly index media items on your custom domain, improving SEO.

To make a media request using a custom hostname, reconstruct the URL to combine the custom hostname, relative path /v1/media/edge/images/, and relative path to the media item.

For example, if the Experience Edge media item URL is:

http://edge.sitecorecloud.io/yourcompany1-yourcompanyltd-p49d-fb1a/media/path/to/mediaFolder/HeroBanner.png

and your registered custom hostname is:

media.your-company.com

Then you can request the media item from the custom hostname URL:

https://media.your-company.com/v1/media/edge/images/yourcompany1-yourcompanyltd-p49d-fb1a/media/path/to/mediaFolder/HeroBanner.png

Custom hostname GraphQL requests

Without a configured defaultSiteId, the site must be supplied explicitly. This exposes the site name in the request payload.

POST https://www.example.com/v1/content/api/graphql/v1

query {
  layout(site: "website", routePath: "/") {
    item {
      rendered
    }
  }
}

With a configured defaultSiteId, Sitecore automatically resolves the site associated with the hostname and while the site parameter must be included in every request, the site name does not need to be supplied.

POST https://www.example.com/v1/content/api/graphql/v1

query {
  layout(site: "" language "en", routePath: "/") {
    item {
      rendered
    }
  }
}

If you have suggestions for improving this article, let us know!