sitecore Collections API

openapi: 3.2.0
info:
  title: Sitecore XM Cloud REST Collections 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: 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.
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'
components:
  schemas:
    CreateCollectionRequest:
      type: object
      description: Request body for creating or updating a site collection
      required:
      - name
      properties:
        name:
          type: string
          description: The name for the site collection
          maxLength: 100
        displayName:
          type: string
          description: The human-readable display name for the collection
    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
    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
    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'
    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
    collectionId:
      name: collectionId
      in: path
      description: The unique identifier of the site collection
      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