Sitecore API catalog
/
Sitecore XM Apps REST API
/
Sites
/
List rendering hosts for a site

Sitecore XM Apps REST API (v1)

Use the XM Apps REST API for managing sites, site collections, pages, and languages in the XM Apps system.

This API lets you interact with:

  • The Site Collection object. Use a site collection to group together related sites that share the same resources.
  • The Site object. The site object is the core entity that represents a website in the customer portfolio.
  • The Language object. The language object is used to manage the languages available to a tenant and site.
  • The Job object. The job object is used to manage running background jobs.

Note the following:

  • All API requests are made in your production environment.

For more information, see the official Sitecore XM Cloud developer documentation.

Authorization

To authorize your requests, use environment automation client credentials and generate a JSON Web Token (JWT).

Note: To create client credentials, you must be an Organization Admin or Organization Owner.

Create an automation client

  1. In the Sitecore Cloud Portal, open XM Cloud Deploy.
  2. Click Credentials > Environment > Create credentials > Automation.
  3. Fill out the automation client details, then click Create.
  4. Copy the client ID and the client secret because you won't be able to view them again in XM Cloud Deploy. You'll use them to request a JWT.

Request a JWT

Run the following cURL command to request a JWT. Replace the placeholder values with your client ID and client secret.

  curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.sitecorecloud.io'

In the response, the access_token key contains the JWT:

  {
    "access_token": "{YOUR_JWT}",
    "scope": "xmcloud.cm:admin",
    "expires_in": 86400,
    "token_type": "Bearer"
  }

The JWT expires in 24 hours. If your requests unexpectedly return a response with status 401 Unauthorized, request a new JWT by repeating this POST request.

We recommend that you cache the JWT for 24 hours to avoid repeating this POST request while the JWT is still valid.

Include the JWT in the request header

You can now start making REST API requests. You must include the JWT in the request header of every request. For example:

curl -X GET '{YOUR_BASE_URL}/...' \
-H 'Authorization: Bearer {YOUR_JWT}' \
-H 'Accept: application/json'
Download OpenAPI description
index.json
index.yaml
Overview
License Apache 2.0
Languages
Servers
Production server
https://xmapps-api.sitecorecloud.io/

Sites

The Sites API lets you create and manage sites for an environment. Learn more about Sites.

Operations

List sites

Request

Fetches the list of sites in the environment, with associated details.

curl -i -X GET \
  https://xmapps-api.sitecorecloud.io/api/v1/sites \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Bodyapplication/jsonArray [
idstring or null

The identifier of the site. Example value: 497f6eca-6276-4993-bfeb-53cbbbba6f08

Example: "497f6eca-6276-4993-bfeb-53cbbbba6f08"
namestring or null

The name of the site. Example value: skate-park

Example: "skate-park"
descriptionstring or null

The description of the site. Example value: New site for Brand A in English-speaking countries

Example: "New site for Brand A in English-speaking countries"
displayNamestring or null

The display name of the site. Example value: Skate Park Website

Example: "Skate Park Website"
thumbnailobject(Thumbnail)

The thumbnail response entity.

collectionIdstring or null

The identifier of the collection to which the site belongs. Example value: 5aae1eeaea2440bf96f11f43da82c77b

Example: "5aae1eeaea2440bf96f11f43da82c77b"
createdstring(date-time)

The date when the site was created. Example value: 2019-08-24T14:15:22Z

Example: "2019-08-24T14:15:22Z"
createdBystring or null

The ID of the user who created the site. Example value: L6kfw52ZVf

Example: "L6kfw52ZVf"
sortOrderinteger or null(int32)

Sort order of the site.

Example: 100
permissionsobject(Permissions)

The access rights of the current user to the site.

languagesArray of strings or null

The list of languages in use by the site.

Example: ["en-US","en-CA"]
hostsArray of objects or null(Host)

The list of hosts that the site resolves to.

supportedLanguagesArray of strings or null

The list of languages supported by Sitecore.

Example: ["en-US","en-CA"]
errorPagesobject(ErrorPages)

An object containing the site error pages

settingsobject or null

The settings for the site.

Example: {"thumbnailsRootPath":"/sitecore/media library/Project/sample-collection/sample-site","generateThumbnails":"true"}
propertiesobject or null

The read-only properties of the site.

Example: {"SxaSiteTemplate":"{E46F3AF2-39FA-4866-A157-7017C4B2A40C}","IsSxaSite":"true"}
]
Response
application/json
[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "skate-park",
    "description": "New site for Brand A in English-speaking countries",
    "displayName": "Skate Park Website",
    "thumbnail": { … },
    "collectionId": "5aae1eeaea2440bf96f11f43da82c77b",
    "created": "2019-08-24T14:15:22Z",
    "createdBy": "L6kfw52ZVf",
    "sortOrder": 100,
    "permissions": { … },
    "languages": [ … ],
    "hosts": [ … ],
    "supportedLanguages": [ … ],
    "errorPages": { … },
    "settings": { … },
    "properties": { … }
  }
]

Create a site

Request

Creates a site for the environment. Sites are created using site templates. Every site belongs to a site collection. You can either create a site inside an existing collection or create a new one. It is also possible to create a site by duplicating a site.

Body
required

Input model

languagestringnon-emptyrequired

The language for the site. If you do not know what languages are available in the environment, first retrieve the list of languages. If the language you want is not available in the environment, add the language first. Example value: en

Example: "en"
siteNamestring[ 0 .. 50 ] characters^(?![\s-])[a-zA-Z0-9_\s-]*(?<!\s)$required

The name of the site. Example value: skate-park

Default "string"
Example: "skate-park"
templateIdstringnon-empty(?i)^(?:[({][0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?...required

The ID of the template used to create the site. If you don't know the template ID, first retrieve site templates. Example value: 5aae1eeaea2440bf96f11f43da82c77b

Example: "5aae1eeaea2440bf96f11f43da82c77b"
displayNamestring or null[ 0 .. 50 ] characters

The display name for the site. Example value: Skate Park Site

Example: "Skate Park Site"
collectionIdstring or null(?i)^(?:[({][0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?...

The ID of the collection you want the new site to belong to. If you don't know the collection ID, first retrieve collections. Required if Sitecore.XmApps.Sites.Models.REST.NewSiteInput.CollectionName is not provided. If left empty, you must provide collectionName instead and a new collection will be created along with the newly created site. If both collectionId and collectionName are provided, collectionName will be ignored. Example value: 5aae1eeaea2440bf96f11f43da82c77b

Example: "5aae1eeaea2440bf96f11f43da82c77b"
languagesArray of strings or null

The list of supported languages for the site.

Example: ["en","da"]
hostNamestring or null

Optional hostname for the new site. Default value: * Example value: dev.skate-park.com

Example: "dev.skate-park.com"
descriptionstring or null[ 0 .. 100 ] characters

Optional text that provides a meaningful description of the site. Example value: New site for Brand A in English-speaking countries.

Example: "New site for Brand A in English-speaking countries."
collectionNamestring or null[ 0 .. 50 ] characters^(?![\s-])[a-zA-Z0-9_\s-]*(?<!\s)$

The name of the new collection you want the new site to belong to. Required if Sitecore.XmApps.Sites.Models.REST.NewSiteInput.CollectionId is not provided. If left empty, you must provide collectionId of an existing collection you want the new site to belong to. If both collectionId and collectionName are provided, collectionName will be ignored. Example value: Brand A

Example: "Brand A"
collectionDisplayNamestring or null[ 0 .. 50 ] characters

The display name for the collection. Example value: Skate Park Site

Example: "Skate Park Site"
collectionDescriptionstring or null[ 0 .. 100 ] characters

If you want to create a new site collection while creating a new site, you can provide a collection description. Example value: Sample description for the site collection containing Sites for Brand A

Example: "Sample description for the site collection containing Sites for Brand A"
posMappingsArray of objects or null(AnalyticsIdentifier)

The site identifier for the site. This identifier lets you control analytics and personalization for the site.

curl -i -X POST \
  https://xmapps-api.sitecorecloud.io/api/v1/sites \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "siteName": "skate-park",
    "displayName": "Skate Park Site",
    "templateId": "5aae1eeaea2440bf96f11f43da82c77b",
    "collectionId": "5aae1eeaea2440bf96f11f43da82c77b",
    "language": "en",
    "languages": [
      "en",
      "da"
    ],
    "hostName": "dev.skate-park.com",
    "description": "New site for Brand A in English-speaking countries.",
    "collectionName": "Brand A",
    "collectionDisplayName": "Skate Park Site",
    "collectionDescription": "Sample description for the site collection containing Sites for Brand A",
    "posMappings": [
      {
        "name": "skate-park",
        "language": "en"
      }
    ]
  }'

Responses

Successful operation

Bodyapplication/json
string
Response
application/json
"string"

Retrieve a site

Request

Fetches information about a site.

Path
siteIdstringrequired

The identifier of the site.

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
curl -i -X GET \
  'https://xmapps-api.sitecorecloud.io/api/v1/sites/{siteId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Bodyapplication/json
idstring or null

The identifier of the site. Example value: 497f6eca-6276-4993-bfeb-53cbbbba6f08

Example: "497f6eca-6276-4993-bfeb-53cbbbba6f08"
namestring or null

The name of the site. Example value: skate-park

Example: "skate-park"
descriptionstring or null

The description of the site. Example value: New site for Brand A in English-speaking countries

Example: "New site for Brand A in English-speaking countries"
displayNamestring or null

The display name of the site. Example value: Skate Park Website

Example: "Skate Park Website"
thumbnailobject(Thumbnail)

The thumbnail response entity.

collectionIdstring or null

The identifier of the collection to which the site belongs. Example value: 5aae1eeaea2440bf96f11f43da82c77b

Example: "5aae1eeaea2440bf96f11f43da82c77b"
createdstring(date-time)

The date when the site was created. Example value: 2019-08-24T14:15:22Z

Example: "2019-08-24T14:15:22Z"
createdBystring or null

The ID of the user who created the site. Example value: L6kfw52ZVf

Example: "L6kfw52ZVf"
sortOrderinteger or null(int32)

Sort order of the site.

Example: 100
permissionsobject(Permissions)

The access rights of the current user to the site.

languagesArray of strings or null

The list of languages in use by the site.

Example: ["en-US","en-CA"]
hostsArray of objects or null(Host)

The list of hosts that the site resolves to.

supportedLanguagesArray of strings or null

The list of languages supported by Sitecore.

Example: ["en-US","en-CA"]
errorPagesobject(ErrorPages)

An object containing the site error pages

settingsobject or null

The settings for the site.

Example: {"thumbnailsRootPath":"/sitecore/media library/Project/sample-collection/sample-site","generateThumbnails":"true"}
propertiesobject or null

The read-only properties of the site.

Example: {"SxaSiteTemplate":"{E46F3AF2-39FA-4866-A157-7017C4B2A40C}","IsSxaSite":"true"}
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "skate-park",
  "description": "New site for Brand A in English-speaking countries",
  "displayName": "Skate Park Website",
  "thumbnail": {
    "url": "https://xmc-customer-tenant.sitecorecloud.io/-/media/Project/sample-collection/sample-site/System/7/0/B/C/thumbnail_70BC64BDE257400E82BFDB3344797DB7.png",
    "rootPath": "sitecore/media library/Project/sample-collection/sample-site",
    "autogenerated": true
  },
  "collectionId": "5aae1eeaea2440bf96f11f43da82c77b",
  "created": "2019-08-24T14:15:22Z",
  "createdBy": "L6kfw52ZVf",
  "sortOrder": 100,
  "permissions": {
    "canAdmin": false,
    "canWrite": false,
    "canCreate": false,
    "canDelete": false,
    "canRename": false,
    "canRead": false,
    "canPublish": false,
    "canDuplicate": false
  },
  "languages": [
    "en-US",
    "en-CA"
  ],
  "hosts": [
    { … }
  ],
  "supportedLanguages": [
    "en-US",
    "en-CA"
  ],
  "errorPages": {
    "errorPage": "string",
    "notFoundPage": "string"
  },
  "settings": {
    "thumbnailsRootPath": "/sitecore/media library/Project/sample-collection/sample-site",
    "generateThumbnails": "true"
  },
  "properties": {
    "SxaSiteTemplate": "{E46F3AF2-39FA-4866-A157-7017C4B2A40C}",
    "IsSxaSite": "true"
  }
}

Update a site

Request

Updates various parameters of a site. To change the name of a site, see rename a site.

Path
siteIdstringrequired

The identifier of the site.

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
Body

Various site configuration properties

displayNamestring or null[ 0 .. 50 ] characters

The display name for the site. Example value: Skate Park Site

Default "string"
Example: "Skate Park Site"
descriptionstring or null[ 0 .. 100 ] characters

The description for the site. Example value: New site for Brand A in English-speaking countries.

Default "string"
Example: "New site for Brand A in English-speaking countries."
supportedLanguagesArray of strings or null

The list of languages supported by Sitecore.

Example: ["en-US","en-CA"]
sharedboolean or null

Indicates if the site should be marked as shared or not

errorPagesobject(ErrorPages)

An object containing the site error pages

sortOrderinteger or null(int32)

The sort order of the site.

Example: 100