sitecore Selections API

openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Selections 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: Selections
  description: Endpoints for managing entity selections across selection pools, allowing grouping of entities for bulk operations or editorial workflows.
paths:
  /selections:
    get:
      operationId: listSelections
      summary: List selections
      description: Retrieves all entity selections across selection pools. Selections group entities for bulk operations such as download, export, or editorial actions.
      tags:
      - Selections
      responses:
        '200':
          description: List of selections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Selection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSelection
      summary: Create a selection
      description: Creates a new entity selection in a specified selection pool. Selections hold a list of entity identifiers for subsequent bulk operations.
      tags:
      - Selections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSelectionRequest'
      responses:
        '201':
          description: Selection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Selection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CreateSelectionRequest:
      type: object
      description: Request body for creating a selection
      required:
      - entityIds
      properties:
        name:
          type: string
          description: Optional name for the selection pool
        entityIds:
          type: array
          description: Entity identifiers to include in the selection
          items:
            type: integer
    ErrorResponse:
      type: object
      description: An error response body
      properties:
        message:
          type: string
          description: A human-readable error message
        statusCode:
          type: integer
          description: The HTTP status code
        errors:
          type: array
          description: List of detailed error messages
          items:
            type: string
    Selection:
      type: object
      description: A named selection pool containing entity identifiers
      properties:
        id:
          type: string
          description: The unique identifier of the selection
        name:
          type: string
          description: The name of the selection pool
        entityIds:
          type: array
          description: The entity identifiers included in this selection
          items:
            type: integer
        createdOn:
          type: string
          description: The ISO 8601 timestamp when the selection was created
          format: date-time
  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