sitecore Flow Definitions API

openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Flow Definitions 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: Flow Definitions
  description: Endpoints for creating, retrieving, and updating flow definitions that represent experiments, experiences, and personalization flows in Sitecore Personalize. Flows can be web-based, full-stack, or triggered by API calls.
paths:
  /v1/flow-definitions:
    get:
      operationId: listFlowDefinitions
      summary: List flow definitions
      description: Retrieves a paginated collection of all flow definitions configured in the Sitecore Personalize instance. Flow definitions represent experiments, full-stack experiences, and API-triggered personalization flows.
      tags:
      - Flow Definitions
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageOffset'
      - $ref: '#/components/parameters/sortBy'
      - name: type
        in: query
        description: Filter flow definitions by type
        required: false
        schema:
          type: string
          enum:
          - WEB
          - FULLSTACK
          - API
      responses:
        '200':
          description: A paginated list of flow definitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowDefinitionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createFlowDefinition
      summary: Create a flow definition
      description: Creates a new flow definition representing a personalization experiment or experience. Flow definitions contain variant configurations, targeting rules, and scheduling settings.
      tags:
      - Flow Definitions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFlowDefinitionRequest'
      responses:
        '201':
          description: Flow definition created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/flow-definitions/{id}:
    get:
      operationId: getFlowDefinition
      summary: Get a flow definition
      description: Retrieves a specific flow definition by its unique identifier. Returns the full definition including type, variant configuration, status, and scheduling.
      tags:
      - Flow Definitions
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Flow definition details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateFlowDefinition
      summary: Update a flow definition
      description: Performs a full replacement update of a flow definition. All fields are replaced with the values in the request body.
      tags:
      - Flow Definitions
      parameters:
      - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFlowDefinitionRequest'
      responses:
        '200':
          description: Flow definition updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication credentials are 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'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    VariantConfig:
      type: object
      description: Configuration for a variant within a decision model or flow
      properties:
        variantRef:
          type: string
          description: The identifier of the variant
        split:
          type: integer
          description: The percentage of traffic allocated to this variant
          minimum: 0
          maximum: 100
    CreateFlowDefinitionRequest:
      type: object
      description: Request body for creating or updating a flow definition
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: The display name of the flow
        type:
          type: string
          description: The type of flow
          enum:
          - WEB
          - FULLSTACK
          - API
        status:
          type: string
          description: The deployment status of the flow
          enum:
          - DRAFT
          - ACTIVE
          - PAUSED
    FlowDefinition:
      type: object
      description: A flow definition representing a personalization experiment or experience in Sitecore Personalize
      properties:
        ref:
          type: string
          description: The unique identifier of the flow definition
        name:
          type: string
          description: The display name of the flow
        type:
          type: string
          description: The type of flow
          enum:
          - WEB
          - FULLSTACK
          - API
        status:
          type: string
          description: The current deployment status of the flow
          enum:
          - DRAFT
          - ACTIVE
          - PAUSED
          - ENDED
          - ARCHIVED
        variants:
          type: array
          description: Variant configurations for the flow
          items:
            $ref: '#/components/schemas/VariantConfig'
        createdAt:
          type: string
          description: The ISO 8601 timestamp when the flow was created
          format: date-time
        modifiedAt:
          type: string
          description: The ISO 8601 timestamp when the flow was last modified
          format: date-time
    FlowDefinitionListResponse:
      type: object
      description: A paginated list of flow definitions
      properties:
        items:
          type: array
          description: The flow definitions for the current page
          items:
            $ref: '#/components/schemas/FlowDefinition'
        total:
          type: integer
          description: Total number of flow definitions
  parameters:
    resourceId:
      name: id
      in: path
      description: The unique identifier of the resource
      required: true
      schema:
        type: string
    sortBy:
      name: sort
      in: query
      description: Field name and direction to sort results by (e.g., name:asc)
      required: false
      schema:
        type: string
    pageOffset:
      name: pageOffset
      in: query
      description: Number of records to skip for pagination
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    pageSize:
      name: pageSize
      in: query
      description: Number of items to return per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  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