Sitecore API catalog
/
Sitecore XM Apps REST API
/
Collections
/
Retrieve a site collection

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

Collections

Site collections are used to group related sites together. The Collections API enables authorized developers to manage site collections.

Operations

List site collections

Request

Fetches the list of site collections in the environment, with associated details.

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

Responses

Success

Bodyapplication/jsonArray [
idstring or null

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

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

The unique system name of the site collection. Example value: skate-park-sites

Example: "skate-park-sites"
descriptionstring or null

The description of the site collection. Example value: Collection for all Skate Park brand websites.

Example: "Collection for all Skate Park brand websites."
displayNamestring or null

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

Example: "Skate Park Websites"
sortOrderinteger or null(int32)

Sort order of the site collection.

Example: 100
createdBystring or null

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

Example: "L6kfw52ZVf"
createdstring(date-time)

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

Example: "2019-08-24T14:15:22Z"
permissionsobject(Permissions)

The access rights of the current user to the site.

settingsobject or null

The site collection settings.

Example: {"itemPath":"/sitecore/content/skate-park-sites"}
]
Response
application/json
[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "skate-park-sites",
    "description": "Collection for all Skate Park brand websites.",
    "displayName": "Skate Park Websites",
    "sortOrder": 100,
    "createdBy": "L6kfw52ZVf",
    "created": "2019-08-24T14:15:22Z",
    "permissions": { … },
    "settings": { … }
  }
]

Create a site collection

Request

Creates a collection by specifying a name and, optionally, a display name and description.

Body

Input data containing name and the description of the site collection

namestring[ 0 .. 50 ] characters^(?![\s-])[a-zA-Z0-9_\s-]*(?<!\s)$required

The unique system name of the new collection. Example value: skate-brand-sites

Default "string"
Example: "skate-brand-sites"
displayNamestring or null[ 0 .. 50 ] characters

A short, meaningful name for the collection. Example value: Skate Brand Websites

Example: "Skate Brand Websites"
descriptionstring or null[ 0 .. 100 ] characters

A longer, more detailed description of the collection. Example value: Collection for all Skate Park brand websites.

Example: "Collection for all Skate Park brand websites."
curl -i -X POST \
  https://xmapps-api.sitecorecloud.io/api/v1/collections \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "skate-brand-sites",
    "displayName": "Skate Brand Websites",
    "description": "Collection for all Skate Park brand websites."
  }'

Responses

Successful operation

Bodyapplication/json
string
Response
application/json
"string"

Retrieve a site collection

Request

Fetches information about a site collection.

Path
collectionIdstringrequired

The identifier of the site collection.

Example: ff34f39f190b4079bf8a0242200b6780
curl -i -X GET \
  'https://xmapps-api.sitecorecloud.io/api/v1/collections/{collectionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Bodyapplication/json
idstring or null

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

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

The unique system name of the site collection. Example value: skate-park-sites

Example: "skate-park-sites"
descriptionstring or null

The description of the site collection. Example value: Collection for all Skate Park brand websites.

Example: "Collection for all Skate Park brand websites."
displayNamestring or null

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

Example: "Skate Park Websites"
sortOrderinteger or null(int32)

Sort order of the site collection.

Example: 100
createdBystring or null

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

Example: "L6kfw52ZVf"
createdstring(date-time)

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

Example: "2019-08-24T14:15:22Z"
permissionsobject(Permissions)

The access rights of the current user to the site.

settingsobject or null

The site collection settings.

Example: {"itemPath":"/sitecore/content/skate-park-sites"}
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "skate-park-sites",
  "description": "Collection for all Skate Park brand websites.",
  "displayName": "Skate Park Websites",
  "sortOrder": 100,
  "createdBy": "L6kfw52ZVf",
  "created": "2019-08-24T14:15:22Z",
  "permissions": {
    "canAdmin": false,
    "canWrite": false,
    "canCreate": false,
    "canDelete": false,
    "canRename": false,
    "canRead": false,
    "canPublish": false,
    "canDuplicate": false
  },
  "settings": {
    "itemPath": "/sitecore/content/skate-park-sites"
  }
}

Update a site collection

Request

Updates the display name and the description of the site collection. To change the system name of a collection, see rename a site collection.

Path
collectionIdstringrequired

The identifier of the site collection.

Example: ff34f39f190b4079bf8a0242200b6780
Body

Input data containing name and the description of the site collection

displayNamestring or null[ 0 .. 50 ] characters

Display name for the site collection. Example value: Skate Brand Websites

Default "string"
Example: "Skate Brand Websites"
descriptionstring or null[ 0 .. 100 ] characters

Description of the site collection. Example value: Example site collection description.

Default "string"
Example: "Example site collection description."
sortOrderinteger or null(int32)

The name of the site collection.

Example: 100
curl -i -X PATCH \
  'https://xmapps-api.sitecorecloud.io/api/v1/collections/{collectionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Skate Brand Websites",
    "description": "Example site collection description.",
    "sortOrder": 100
  }'

Responses

Successful operation

Bodyapplication/json
idstring or null

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

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

The unique system name of the site collection. Example value: skate-park-sites

Example: "skate-park-sites"
descriptionstring or null

The description of the site collection. Example value: Collection for all Skate Park brand websites.

Example: "Collection for all Skate Park brand websites."
displayNamestring or null

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

Example: "Skate Park Websites"
sortOrderinteger or null(int32)

Sort order of the site collection.

Example: 100
createdBystring or null

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

Example: "L6kfw52ZVf"
createdstring(date-time)

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

Example: "2019-08-24T14:15:22Z"
permissionsobject(Permissions)

The access rights of the current user to the site.

settingsobject or null

The site collection settings.

Example: {"itemPath":"/sitecore/content/skate-park-sites"}
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "skate-park-sites",
  "description": "Collection for all Skate Park brand websites.",
  "displayName": "Skate Park Websites",
  "sortOrder": 100,
  "createdBy": "L6kfw52ZVf",
  "created": "2019-08-24T14:15:22Z",
  "permissions": {
    "canAdmin": false,
    "canWrite": false,
    "canCreate": false,
    "canDelete": false,
    "canRename": false,
    "canRead": false,
    "canPublish": false,
    "canDuplicate": false
  },
  "settings": {
    "itemPath": "/sitecore/content/skate-park-sites"
  }
}

Delete a site collection

Request

Deletes a site collection, including sites in that collection.

Path
collectionIdstringrequired

The identifier of the site collection.

Example: ff34f39f190b4079bf8a0242200b6780
curl -i -X DELETE \
  'https://xmapps-api.sitecorecloud.io/api/v1/collections/{collectionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Bodyapplication/json
string
Response
application/json
"string"

Rename a site collection

Request

Changes the system name of a site collection.

Path
collectionIdstringrequired

The identifier of the site collection.

Example: ff34f39f190b4079bf8a0242200b6780
Body
required

Input object containing the new system name of the site collection.

systemNamestring[ 0 .. 50 ] characters^(?![\s-])[a-zA-Z0-9_\s-]*(?<!\s)$required

The new system name for the site collection. Example value: skate-brand-sites

Default "string"
Example: "skate-brand-sites"
curl -i -X POST \
  'https://xmapps-api.sitecorecloud.io/api/v1/collections/{collectionId}/rename' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "systemName": "skate-brand-sites"
  }'

Responses

Successful operation

Bodyapplication/json
string
Response
application/json
"string"

Sort site collections

Request

By assigning a sort value to site collection IDs, you can use this endpoint to apply an order by which collections are sorted in the Sites user interface and in Content Editor. The lower the sort value, the higher the site appears in the interface.

Body
required

A collections JSON object of key-value pairs where the collection ID (string) is the key and the sort order (integer) is the value.

collectionsobject or null

A collection containing collection IDs and sort order.

Example: {"{E7ACF719-9448-4B82-B9E9-E35E612392B1}":0,"{3BB5127B-9B19-479E-A560-DDAB73050C0D}":100,"{1E3D6D62-2EE7-4B99-B973-9C861E535236}":200}
curl -i -X POST \
  https://xmapps-api.sitecorecloud.io/api/v1/collections/sort \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collections": {
      "{E7ACF719-9448-4B82-B9E9-E35E612392B1}": 0,
      "{3BB5127B-9B19-479E-A560-DDAB73050C0D}": 100,
      "{1E3D6D62-2EE7-4B99-B973-9C861E535236}": 200
    }
  }'

Responses

Site collections sort order updated successfully

Response
application/json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "A detailed explanation, specific to this occurrence of the problem.",
  "instance": "If available, a URI reference that identifies the specific occurrence of the problem.",
  "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00",
  "errors": {
    "sampleProperty": [ … ]
  }
}

Validate site collection name

Request

Validates a site collection name to ensure it meets the required criteria. The validations applied to the collection name:

  • Is a string and can't be null.
  • Is unique.
  • The length of the name is a maximum of 50 characters.
  • Can't start or end with a space.
  • Can't start with a dash.
  • Can include Latin alphanumeric characters, spaces and dashes.
Body
required

The site collection name to validate.

namestring or null

The name of the site collection to validate.

curl -i -X POST \
  https://xmapps-api.sitecorecloud.io/api/v1/collections/name/validate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string"
  }'

Responses

Returns a NameValidationResult indicating the validation result.

Bodyapplication/json
isValidboolean

indicates whether the name is valid.

messagestring or null

details about the request.

Response
application/json
{
  "isValid": true,
  "message": "string"
}

List sites in a site collection

Request

Fetches a list of sites in a site collection.

Path
collectionIdstringrequired

The identifier of the site collection.

Example: ff34f39f190b4079bf8a0242200b6780
curl -i -X GET \
  'https://xmapps-api.sitecorecloud.io/api/v1/collections/{collectionId}/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": { … }
  }
]

Jobs

The Jobs API allows callers to manage running background jobs.

Operations

Languages

XM Cloud supports creating content and websites in multiple languages. The default language is English, but you can add any number of languages to your environment, languages that you can select amongst the predefined languages that are supported by Sitecore XM Cloud. Sitecore supports all the languages available in the .NET CultureInfo class. A predefined language in XM Cloud follows the ISO code and combines both language and country or region, for example, en-AU or English(Australia).

Operations