Sitecore API catalog
/
Sitecore XM Apps REST API
/
Jobs

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

Jobs

The Jobs API allows callers to manage running background jobs.

Operations

List site job statuses

Request

Fetches information about background jobs. Returns empty array if no jobs are running.

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

Responses

Successful operation

Bodyapplication/jsonArray [
namestring or null

The name of the job. Example value: Create site

Example: "Create site"
doneboolean

Indicates whether the job has finished.

queueTimestring(date-time)

A timestamp of when the job was added to the queue. Example value: 2024-06-12T01:47:37.316Z

Example: "2024-06-12T01:47:37.316Z"
handlestring or null

The handle of the job. Example value: 4d97d35a-b605-4fc6-8a03-5bb8e403cdaf;customer-tenant-env

Example: "4d97d35a-b605-4fc6-8a03-5bb8e403cdaf;customer-tenant-env"
sitestring or null

The name of the site. Example value: new-site

Example: "new-site"
siteCollectionstring or null

The identifier or name of the site collection. Example value: {81D27BA9-F798-4190-8536-CA20203AA6EA}

Example: "{81D27BA9-F798-4190-8536-CA20203AA6EA}"
]
Response
application/json
[
  {
    "name": "Create site",
    "done": true,
    "queueTime": "2024-06-12T01:47:37.316Z",
    "handle": "4d97d35a-b605-4fc6-8a03-5bb8e403cdaf;customer-tenant-env",
    "site": "new-site",
    "siteCollection": "{81D27BA9-F798-4190-8536-CA20203AA6EA}"
  }
]

Retrieve a job status

Request

Fetches information about a background job.

Path
jobHandlestringrequired

The handle of the job. If you don’t know the handle of the job, first retrieve the list of site job statuses.

curl -i -X GET \
  'https://xmapps-api.sitecorecloud.io/api/v1/jobs/{jobHandle}/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation

Bodyapplication/json
namestring or null

The name of the job. Example value: Create site

Example: "Create site"
doneboolean

Indicates whether the job has finished.

queueTimestring(date-time)

A timestamp of when the job was added to the queue. Example value: 2024-06-12T01:47:37.316Z

Example: "2024-06-12T01:47:37.316Z"
handlestring or null

The handle of the job. Example value: 4d97d35a-b605-4fc6-8a03-5bb8e403cdaf;customer-tenant-env

Example: "4d97d35a-b605-4fc6-8a03-5bb8e403cdaf;customer-tenant-env"
sitestring or null

The name of the site. Example value: new-site

Example: "new-site"
siteCollectionstring or null

The identifier or name of the site collection. Example value: {81D27BA9-F798-4190-8536-CA20203AA6EA}

Example: "{81D27BA9-F798-4190-8536-CA20203AA6EA}"
Response
application/json
{
  "name": "Create site",
  "done": true,
  "queueTime": "2024-06-12T01:47:37.316Z",
  "handle": "4d97d35a-b605-4fc6-8a03-5bb8e403cdaf;customer-tenant-env",
  "site": "new-site",
  "siteCollection": "{81D27BA9-F798-4190-8536-CA20203AA6EA}"
}

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