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). The token is valid for all the environments in an organization.

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
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