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

In the Sitecore Cloud Portal, open XM Cloud Deploy.
Click Credentials > Environment > Create credentials > Automation.
Fill out the automation client details, then click Create.
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

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

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

List languages

Request

Retrieves the list of languages added to the environment.

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

Responses

Successful operation

Bodyapplication/jsonArray [

idstring or null

The identifier of the language. Example value: af58419145c9420187405409f4cf8bdd

Example: "af58419145c9420187405409f4cf8bdd"

isostring or null

The ISO code of the language. Example value: en

Example: "en"

regionalIsoCodestring or null

The regional ISO code of the language, for example, US for the USA, or DK for Denmark. Example value: en-US

Example: "en-US"

fallbackLanguageIsostring or null

The ISO code of the fallback language Example value: en

Example: "en"

namestring or null

The ISO language code (e.g., "en" for English, "es" for Spanish). Example value: en-US

Example: "en-US"

displayNamestring or null

The human-readable name of the language as it appears in the user interface, for example, "English" or "Español." Example value: English (United States) : English (United States)

Example: "English (United States) : English (United States)"

nativeNamestring or null

The language name in its original script or characters. For instance, "English" would be displayed as "English" itself, but "日本語" would appear as "日本語." Example value: English (United States)

Example: "English (United States)"

englishNamestring or null

The language name in English, regardless of the language being described. For example, "Deutsch" would be displayed as "German." Example value: English (United States)

Example: "English (United States)"

baseIsoCultureCodestring or null

Base ISO culture code. If this is a custom language, this ISO culture code will represent the language code used as the base of this language. For example, if the custom language uses the same writing system, calendar, and date format as American English, the value would be 'en-US'. Example value: en-US

Example: "en-US"

fallbackRegionDisplayNamestring or null

If this is a custom language, the Fallback Region Display Name respresents the region name that should be displayed. Example value: North America

Example: "North America"

]

Response

application/json

[
  {
    "id": "af58419145c9420187405409f4cf8bdd",
    "iso": "en",
    "regionalIsoCode": "en-US",
    "fallbackLanguageIso": "en",
    "name": "en-US",
    "displayName": "English (United States) : English (United States)",
    "nativeName": "English (United States)",
    "englishName": "English (United States)",
    "baseIsoCultureCode": "en-US",
    "fallbackRegionDisplayName": "North America"
  }
]

Add a language

Request

Adds a language to your environment, so you can create content and build websites in that language. You can choose from the language supported by Sitecore XM Cloud. If you do not know the language code of the language, first retrieve the list of languages supported in Sitecore XM Cloud. To add a language to the system, you must provide the language code. You can optionally input additional parameters, such as region code and spell checker. If you want to add a custom language not in the default cultures, register it as a custom culture (as described in .NET CultureInfo class) and update the LanguageDefinitions.config file.

Body

required

Input parameters

languageCodestringnon-emptyrequired

The ISO code for the language. Example value: en

Example: "en"

charsetstring or null

The character encoding, that specifies how characters are represented in a document or web page. Example value: iso-8859-1

Example: "iso-8859-1"

codePagestring or null

Code Page Example value: 65001

Example: "65001"

customCodestring or null

If you wish to support a nonstandard country or region code, you can provide a custom language code. Example value: en-EU

Example: "en-EU"

databasestring or null

Database Example value: master

Example: "master"

encodingstring or null

Example value: utf-8 Example value: utf-8

Example: "utf-8"

namestring or null

The name that will be used for the language. Example value: en-US

Example: "en-US"

regionCodestring or null

The regional ISO code of the language. Example values: US for the USA, or DK for Denmark. Example value: US

Example: "US"

fallbackLanguagestring or null

If you wish to configure fallback for the new language, add the ISO language code for the fallback language. Example value: en

Example: "en"

spellCheckerstring or null

A reference to the dictionary file name that you want to use to spellcheck in the new language. Example value: en-US.tdf

Example: "en-US.tdf"

curl -i -X POST \
  https://xmapps-api.sitecorecloud.io/api/v1/languages \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "charset": "iso-8859-1",
    "codePage": "65001",
    "customCode": "en-EU",
    "database": "master",
    "encoding": "utf-8",
    "languageCode": "en",
    "name": "en-US",
    "regionCode": "US",
    "fallbackLanguage": "en",
    "spellChecker": "en-US.tdf"
  }'

Responses

Successful operation

Bodyapplication/json

idstring or null

The identifier of the language. Example value: af58419145c9420187405409f4cf8bdd

Example: "af58419145c9420187405409f4cf8bdd"

isostring or null

The ISO code of the language. Example value: en

Example: "en"

regionalIsoCodestring or null

The regional ISO code of the language, for example, US for the USA, or DK for Denmark. Example value: en-US

Example: "en-US"

fallbackLanguageIsostring or null

The ISO code of the fallback language Example value: en

Example: "en"

namestring or null

The ISO language code (e.g., "en" for English, "es" for Spanish). Example value: en-US

Example: "en-US"

displayNamestring or null

The human-readable name of the language as it appears in the user interface, for example, "English" or "Español." Example value: English (United States) : English (United States)

Example: "English (United States) : English (United States)"

nativeNamestring or null

Example: "English (United States)"

englishNamestring or null

The language name in English, regardless of the language being described. For example, "Deutsch" would be displayed as "German." Example value: English (United States)

Example: "English (United States)"

baseIsoCultureCodestring or null

Example: "en-US"

fallbackRegionDisplayNamestring or null

If this is a custom language, the Fallback Region Display Name respresents the region name that should be displayed. Example value: North America

Example: "North America"

Response

application/json

{
  "id": "af58419145c9420187405409f4cf8bdd",
  "iso": "en",
  "regionalIsoCode": "en-US",
  "fallbackLanguageIso": "en",
  "name": "en-US",
  "displayName": "English (United States) : English (United States)",
  "nativeName": "English (United States)",
  "englishName": "English (United States)",
  "baseIsoCultureCode": "en-US",
  "fallbackRegionDisplayName": "North America"
}

List supported languages

Request

Retrieves the list of languages supported by Sitecore XM Cloud, and associated data.

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

Responses

Successful operation

Bodyapplication/jsonArray [

namestring or null

The full name of the language. Example value: de-DE

Example: "de-DE"

englishNamestring or null

The english name of the language. Example value: German (Germany)

Example: "German (Germany)"

displayNamestring or null

The display name of the language. Example value: German (Germany) : Deutsch (Deutschland)

Example: "German (Germany) : Deutsch (Deutschland)"

charSetstring or null

The character encoding, that specifies how characters are represented in a document or web page. Example value: iso-8859-1

Example: "iso-8859-1"

codePagestring or null

The code of the page. Example value: 65001

Example: "65001"

encodingstring or null

The encoding. Example value: utf-8

Example: "utf-8"

languageCodestring or null

The code for the language. Example value: de

Example: "de"

regionCodestring or null

The regional ISO code of the language. For example, US for the USA, or DK for Denmark. Example value: DE

Example: "DE"

]

Response

application/json

[
  {
    "name": "de-DE",
    "englishName": "German (Germany)",
    "displayName": "German (Germany) : Deutsch (Deutschland)",
    "charSet": "iso-8859-1",
    "codePage": "65001",
    "encoding": "utf-8",
    "languageCode": "de",
    "regionCode": "DE"
  }
]

Update a language

Request

Updates a language supported by Sitecore XM Cloud. To update a language, you must provide the regional ISO code of the language. If you do not know the ISO code of the language, first retrieve the list of languages supported in Sitecore XM Cloud.

Path

isoCodestringrequired

Regional ISO code of the language to update

Example: en-US

Body

required

Input parameters

languageCodestring or null

regionCodestring or null

fallbackLanguageIsostring or null

baseIsoCultureCodestring or null

fallbackRegionDisplayNamestring or null

curl -i -X PATCH \
  'https://xmapps-api.sitecorecloud.io/api/v1/languages/{isoCode}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "languageCode": "string",
    "regionCode": "string",
    "fallbackLanguageIso": "string",
    "baseIsoCultureCode": "string",
    "fallbackRegionDisplayName": "string"
  }'

Responses

No Content

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": [ … ]
  }
}

Delete a language

Request

Deletes a language from the XM Cloud environment. To delete a language from the system, you must provide the regional ISO code of the language. If you do not know the ISO code of the language, first retrieve the list of languages added to the environment.

Path

isoCodestringrequired

Regional ISO code of the language to remove.

Example: en-US

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

Responses

Successful operation

Bodyapplication/json

boolean

Response

application/json

true

Sitecore XM Apps REST API (v1)

Authorization

Create an automation client

Request a JWT

Include the JWT in the request header

Sites

Collections

Jobs

Languages

List languages

Request

Responses

Was this helpful?

Add a language

Request

Responses

Was this helpful?

List supported languages

Request

Responses

Was this helpful?

Update a language

Request

Responses

Was this helpful?

Delete a language

Request

Responses

Was this helpful?