sitecore Collections API

openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Collections API
  description: The Sitecore CDP REST API provides synchronous access to retrieve, create, update, and delete data stored in Sitecore Customer Data Platform. It exposes guest profiles, orders, order items, order contacts, order consumers, and data extensions through standard HTTP methods. Developers use this API to build integrations that read or write customer data programmatically, enabling use cases such as audience segmentation, data enrichment, and reporting. Authentication uses HTTP Basic Auth with a client key and API token obtained from the CDP instance settings. Regional server endpoints must be used based on the CDP instance's geographic deployment.
  version: v2.1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://api-engage-eu.sitecorecloud.io
  description: EU Production Server
- url: https://api-engage-us.sitecorecloud.io
  description: US Production Server
- url: https://api-engage-ap.sitecorecloud.io
  description: Asia-Pacific Production Server
- url: https://api-engage-jpe.sitecorecloud.io
  description: Japan Production Server
security:
- basicAuth: []
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:
  parameters:
    collectionId:
      name: collectionId
      in: path
      description: The unique identifier of the site collection
      required: true
      schema:
        type: string
    environmentId:
      name: sc_env
      in: query
      description: The XM Cloud environment identifier
      required: false
      schema:
        type: string
  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:
    ValidateNameRequest:
      type: object
      description: Request body for validating a name
      required:
      - name
      properties:
        name:
          type: string
          description: The name to validate
    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
    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
    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
    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
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using a client key as the username and an API token as the password. Credentials are obtained from Sitecore CDP Settings > API access.
externalDocs:
  description: Sitecore CDP REST API Documentation
  url: https://doc.sitecore.com/cdp/en/developers/api/rest-apis.html