openapi: 3.1.0
info:
title: Sitecore XM Cloud REST API
description: >-
The Sitecore XM Cloud REST API provides endpoints for creating and managing
collections, sites, pages, languages, and publishing jobs within an XM Cloud
tenant. It covers the full lifecycle of site and collection management through
the XM Apps system, exposes page authoring operations, and enables programmatic
control of publishing workflows. The API follows RESTful conventions and is
authenticated via OAuth 2.0 tokens obtained from the Sitecore Cloud Portal
automation client credentials. It is organized into several functional areas:
the Sites API for managing sites, site collections, and languages; the Pages
API for managing site pages; and the Publishing API for creating, monitoring,
and managing publishing jobs.
version: 'v1'
contact:
name: Sitecore Support
url: https://www.sitecore.com/support
termsOfService: https://www.sitecore.com/legal/terms-of-service
externalDocs:
description: Sitecore XM Cloud Developer Documentation
url: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-xm-cloud.html
servers:
- url: https://xmapps-api.sitecorecloud.io
description: XM Apps Production Server
- url: https://edge-platform.sitecorecloud.io
description: Experience Edge Platform Server
tags:
- name: Collections
description: >-
Endpoints for creating, retrieving, updating, and deleting site collections
within an XM Cloud tenant. Collections group related sites that share
resources and organizational context.
- name: Languages
description: >-
Endpoints for managing language availability at the tenant and site levels,
including listing supported languages and adding or removing language options.
- name: Pages
description: >-
Endpoints for managing site pages including full CRUD operations, versioning,
variant management, layout editing, field value updates, and publishing state
verification.
- name: Publishing Jobs
description: >-
Endpoints for creating, monitoring, and managing publishing jobs that push
content from XM Cloud authoring to the Experience Edge delivery layer.
- name: Sites
description: >-
Endpoints for managing sites within site collections, including creation,
duplication, renaming, deletion, sorting, and retrieving site hierarchies
and rendering hosts.
security:
- bearerAuth: []
paths:
/api/v1/collections:
get:
operationId: listCollections
summary: List site collections
description: >-
Retrieves a list of all site collections within the authenticated XM Cloud
tenant. Returns collection metadata including names, identifiers, and
associated site counts.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: A list of site collections
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SiteCollection'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCollection
summary: Create a site collection
description: >-
Creates a new site collection within the XM Cloud tenant. Site collections
group related sites together and allow shared resource management. The
collection name must be unique within the tenant.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionRequest'
responses:
'201':
description: Site collection created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SiteCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/collections/{collectionId}:
get:
operationId: getCollection
summary: Get a site collection
description: >-
Retrieves a specific site collection by its unique identifier. Returns
full collection metadata including associated sites and configuration.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/collectionId'
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: Site collection details
content:
application/json:
schema:
$ref: '#/components/schemas/SiteCollection'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCollection
summary: Update a site collection
description: >-
Updates the properties of an existing site collection, such as its name
or description. All updateable fields must be provided in the request body.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/collectionId'
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionRequest'
responses:
'200':
description: Site collection updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SiteCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteCollection
summary: Delete a site collection
description: >-
Permanently deletes a site collection and all of its associated sites.
This operation is irreversible. All sites within the collection must be
removed or the operation will return an error.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/collectionId'
- $ref: '#/components/parameters/environmentId'
responses:
'204':
description: Site collection deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/collections/name/validate:
post:
operationId: validateCollectionName
summary: Validate a site collection name
description: >-
Validates whether a proposed site collection name is available and meets
naming requirements before creating a collection. Returns validation
status and any error messages.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateNameRequest'
responses:
'200':
description: Validation result
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateNameResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/collections/sort:
post:
operationId: sortCollections
summary: Sort site collections
description: >-
Updates the sort order of site collections as they appear in the Content
Editor, Pages, and API responses. Accepts an ordered list of collection
identifiers.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SortRequest'
responses:
'200':
description: Sort order updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/sites:
get:
operationId: listSites
summary: List sites
description: >-
Retrieves a list of all sites within the authenticated XM Cloud tenant,
optionally filtered by collection. Returns site metadata including names,
identifiers, languages, and associated collection references.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/environmentId'
- name: collectionId
in: query
description: Filter sites by parent collection identifier
required: false
schema:
type: string
responses:
'200':
description: A list of sites
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Site'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createSite
summary: Create a site
description: >-
Creates a new site within an XM Cloud site collection. The site can be
created from a template or as a blank site, and the request must specify
the parent collection, name, and language configuration.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSiteRequest'
responses:
'201':
description: Site created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/sites/{siteId}:
get:
operationId: getSite
summary: Get a site
description: >-
Retrieves a specific site by its unique identifier, including its full
configuration, language settings, and collection membership.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/siteId'
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: Site details
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteSite
summary: Delete a site
description: >-
Permanently deletes a site and all of its associated pages and content.
This operation is irreversible and cannot be undone after execution.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/siteId'
- $ref: '#/components/parameters/environmentId'
responses:
'204':
description: Site deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/sites/name/validate:
post:
operationId: validateSiteName
summary: Validate a site name
description: >-
Validates whether a proposed site name is available and meets naming
requirements prior to site creation. Returns validation status and error
details if the name is unavailable or invalid.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateNameRequest'
responses:
'200':
description: Validation result
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateNameResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/sites/sort:
post:
operationId: sortSites
summary: Sort sites
description: >-
Updates the sort order of sites as they appear in the Content Editor,
Pages, and API responses. Accepts an ordered list of site identifiers.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SortRequest'
responses:
'200':
description: Sort order updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/sites/{siteId}/renderinghosts:
get:
operationId: listSiteRenderingHosts
summary: List rendering hosts for a site
description: >-
Returns a list of editing hosts that can be assigned to the specified
site. Rendering hosts define the front-end application endpoints used
for Experience Editor and Pages rendering.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/siteId'
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: List of available rendering hosts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RenderingHost'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/languages:
get:
operationId: listLanguages
summary: List tenant languages
description: >-
Retrieves all languages configured at the tenant level. Languages listed
here are available for assignment to individual sites within the tenant.
tags:
- Languages
parameters:
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: List of tenant languages
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Language'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/languages/supported:
get:
operationId: listSupportedLanguages
summary: List supported languages
description: >-
Returns all languages supported by the XM Cloud platform that can be
added to a tenant or site configuration.
tags:
- Languages
parameters:
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: List of supported languages
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Language'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/sites/{siteId}/languages:
get:
operationId: listSiteLanguages
summary: List site languages
description: >-
Retrieves all languages enabled for a specific site. These languages
determine the locales in which content can be authored and delivered.
tags:
- Languages
parameters:
- $ref: '#/components/parameters/siteId'
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: List of languages for the site
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Language'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: addSiteLanguage
summary: Add a language to a site
description: >-
Adds a language to a site, enabling content authoring and delivery in
that locale. The language must be present in the list of supported
languages before it can be added to a site.
tags:
- Languages
parameters:
- $ref: '#/components/parameters/siteId'
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddLanguageRequest'
responses:
'201':
description: Language added to site
content:
application/json:
schema:
$ref: '#/components/schemas/Language'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/sites/{siteId}/languages/{languageId}:
delete:
operationId: removeSiteLanguage
summary: Remove a language from a site
description: >-
Removes a language from a site, preventing further content authoring
in that locale. Existing content in the language is not deleted but
becomes inaccessible through the site.
tags:
- Languages
parameters:
- $ref: '#/components/parameters/siteId'
- $ref: '#/components/parameters/languageId'
- $ref: '#/components/parameters/environmentId'
responses:
'204':
description: Language removed from site
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/api/v1/pages:
get:
operationId: listPages
summary: List pages
description: >-
Retrieves a list of pages for the specified site and environment. Supports
filtering by language, version, and other attributes. Results are paginated
and include basic page metadata.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/environmentId'
- $ref: '#/components/parameters/siteQueryParam'
- $ref: '#/components/parameters/language'
responses:
'200':
description: A list of pages
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Page'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createPage
summary: Create a page
description: >-
Creates a new page within a site. Pages can be created from blueprints
or as blank pages. The request must specify the parent item, page name,
template, and optionally an insert options configuration.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePageRequest'
responses:
'201':
description: Page created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/pages/{pageId}:
get:
operationId: getPage
summary: Get a page
description: >-
Retrieves a specific page by its identifier. Returns full page metadata
including layout information, version history, field values, and publishing
state for the specified language and version.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/pageId'
- $ref: '#/components/parameters/environmentId'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/version'
responses:
'200':
description: Page details
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deletePage
summary: Delete a page
description: >-
Permanently deletes a page and all its versions and language variants.
This operation is irreversible. Child pages are also deleted unless they
are moved prior to deletion.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/pageId'
- $ref: '#/components/parameters/environmentId'
responses:
'204':
description: Page deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/authoring/publishing/v1/jobs:
get:
operationId: listPublishingJobs
summary: List publishing jobs
description: >-
Retrieves a paginated list of publishing jobs for the authenticated tenant
and environment. Jobs can be filtered by status, date range, and other
criteria. Returns job metadata including status, creation time, and
item processing metrics.
tags:
- Publishing Jobs
parameters:
- $ref: '#/components/parameters/environmentId'
- name: status
in: query
description: Filter jobs by status
required: false
schema:
$ref: '#/components/schemas/JobStatus'
- name: pageSize
in: query
description: Number of jobs to return per page
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: A paginated list of publishing jobs
content:
application/json:
schema:
$ref: '#/components/schemas/PublishingJobList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createPublishingJob
summary: Create a publishing job
description: >-
Creates and queues a new publishing job to push content from XM Cloud
authoring to the Experience Edge delivery layer. The job can target
specific items, languages, or be configured as a full site publish.
tags:
- Publishing Jobs
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePublishingJobRequest'
responses:
'202':
description: Publishing job accepted and queued
content:
application/json:
schema:
$ref: '#/components/schemas/PublishingJob'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/authoring/publishing/v1/jobs/{id}:
get:
operationId: getPublishingJob
summary: Get a publishing job
description: >-
Retrieves a specific publishing job by its identifier. Returns the current
status, progress metrics, and any error information for the job.
tags:
- Publishing Jobs
parameters:
- $ref: '#/components/parameters/jobId'
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: Publishing job details
content:
application/json:
schema:
$ref: '#/components/schemas/PublishingJob'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/authoring/publishing/v1/jobs/{jobId}/cancel:
post:
operationId: cancelPublishingJob
summary: Cancel a publishing job
description: >-
Cancels an active publishing job that is currently queued or running.
Jobs in a terminal state (Completed, Failed, Canceled) cannot be cancelled.
Returns the updated job with a Canceling or Canceled status.
tags:
- Publishing Jobs
parameters:
- $ref: '#/components/parameters/jobId'
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: Publishing job cancellation initiated
content:
application/json:
schema:
$ref: '#/components/schemas/PublishingJob'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/authoring/publishing/v1/jobs/summary:
get:
operationId: getPublishingJobSummary
summary: Get publishing job summary
description: >-
Retrieves statistical summary information about publishing jobs within
the tenant, including counts by status, recent activity metrics, and
item processing totals.
tags:
- Publishing Jobs
parameters:
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: Publishing job statistics summary
content:
application/json:
schema:
$ref: '#/components/schemas/PublishingJobSummary'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT token obtained via OAuth 2.0 client credentials flow. Request tokens
from https://auth.sitecorecloud.io/oauth/token using automation client
credentials created in the Sitecore Cloud Portal. Tokens expire after
24 hours.
parameters:
environmentId:
name: sc_env
in: query
description: The XM Cloud environment identifier
required: false
schema:
type: string
collectionId:
name: collectionId
in: path
description: The unique identifier of the site collection
required: true
schema:
type: string
siteId:
name: siteId
in: path
description: The unique identifier of the site
required: true
schema:
type: string
siteQueryParam:
name: siteId
in: query
description: Filter results by site identifier
required: false
schema:
type: string
languageId:
name: languageId
in: path
description: The language identifier (e.g., en, fr-FR)
required: true
schema:
type: string
pageId:
name: pageId
in: path
description: The unique identifier of the page item
required: true
schema:
type: string
jobId:
name: jobId
in: path
description: The unique identifier of the publishing job
required: true
schema:
type: string
language:
name: language
in: query
description: Language code for the content (e.g., en, fr-FR)
required: false
schema:
type: string
version:
name: version
in: query
description: Content version number to retrieve
required: false
schema:
type: integer
responses:
Unauthorized:
description: Authentication token is missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
BadRequest:
description: The request body or parameters are invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
NotFound:
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
schemas:
SiteCollection:
type: object
description: A site collection that groups related sites within an XM Cloud tenant
properties:
id:
type: string
description: The unique identifier of the site collection
name:
type: string
description: The display name of the site collection
displayName:
type: string
description: The human-readable display name for the collection
sortOrder:
type: integer
description: The sort position of this collection relative to others
sites:
type: array
description: Sites contained within this collection
items:
$ref: '#/components/schemas/SiteSummary'
SiteSummary:
type: object
description: A summary representation of a site within a collection
properties:
id:
type: string
description: The unique identifier of the site
name:
type: string
description: The name of the site
Site:
type: object
description: A website managed within an XM Cloud site collection
properties:
id:
type: string
description: The unique identifier of the site
name:
type: string
description: The name of the site
displayName:
type: string
description: The human-readable display name for the site
collectionId:
type: string
description: The identifier of the parent site collection
languages:
type: array
description: Languages enabled for this site
items:
$ref: '#/components/schemas/Language'
sortOrder:
type: integer
description: The sort position of this site within its collection
renderingHost:
type: string
description: The URL of the rendering host assigned to this site
Language:
type: object
description: A language configuration for a tenant or site
properties:
isoCode:
type: string
description: The ISO language code (e.g., en, fr-FR, de-DE)
example: en
name:
type: string
description: The display name of the language
example: English
nativeName:
type: string
description: The language name in its native script
example: English
RenderingHost:
type: object
description: A rendering host endpoint that can be assigned to a site
properties:
id:
type: string
description: The unique identifier of the rendering host
name:
type: string
description: The display name of the rendering host
url:
type: string
description: The URL of the rendering host endpoint
format: uri
Page:
type: object
description: A page item within an XM Cloud site
properties:
id:
type: string
description: The unique Sitecore item identifier for the page
name:
type: string
description: The item name of the page
displayName:
type: string
description: The display name of the page shown in navigation
path:
type: string
description: The Sitecore item path of the page
language:
type: string
description: The language of the page content
version:
type: integer
description: The version number of the page content
templateId:
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sitecore/refs/heads/main/openapi/sitecore-xm-cloud-rest-api-openapi.yml