sitecore Sites API

openapi: 3.2.0
info:
  title: Sitecore XM Cloud REST Sites 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
servers:
- url: https://xmapps-api.sitecorecloud.io
  description: XM Apps Production Server
- url: https://edge-platform.sitecorecloud.io
  description: Experience Edge Platform Server
security:
- bearerAuth: []
tags:
- name: Sites
  description: Endpoints for managing sites within site collections, including creation, duplication, renaming, deletion, sorting, and retrieving site hierarchies and rendering hosts.
paths:
  /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'
components:
  schemas:
    ValidateNameResponse:
      type: object
      description: Result of a name validation check
      properties:
        isValid:
          type: boolean
          description: Whether the name is valid and available
        errors:
          type: array
          description: List of validation error messages if the name is invalid
          items:
            type: string
    CreateSiteRequest:
      type: object
      description: Request body for creating a new site
      required:
      - name
      - collectionId
      - language
      properties:
        name:
          type: string
          description: The name of the new site
          maxLength: 100
        displayName:
          type: string
          description: The human-readable display name for the site
        collectionId:
          type: string
          description: The identifier of the parent site collection
        language:
          type: string
          description: The default language ISO code for the site
          example: en
        templateId:
          type: string
          description: The identifier of the site template to use for creation
    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
    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
    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
    SortRequest:
      type: object
      description: Request body for updating the sort order of items
      required:
      - ids
      properties:
        ids:
          type: array
          description: Ordered list of item identifiers representing the new sort order
          items:
            type: string
    ValidateNameRequest:
      type: object
      description: Request body for validating a name
      required:
      - name
      properties:
        name:
          type: string
          description: The name to validate
    ProblemDetails:
      type: object
      description: RFC 7807 problem details response for errors
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type
        title:
          type: string
          description: A short human-readable summary of the problem
        status:
          type: integer
          description: The HTTP status code for this occurrence of the problem
        detail:
          type: string
          description: A human-readable explanation of the problem
        instance:
          type: string
          description: A URI reference identifying the specific occurrence of the problem
  parameters:
    environmentId:
      name: sc_env
      in: query
      description: The XM Cloud environment identifier
      required: false
      schema:
        type: string
    siteId:
      name: siteId
      in: path
      description: The unique identifier of the site
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication token is missing or 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'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  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.
externalDocs:
  description: Sitecore XM Cloud Developer Documentation
  url: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-xm-cloud.html