sitecore Flow Definitions API

openapi: 3.2.0
info:
  title: Sitecore Personalize REST Flow Definitions API
  description: The Sitecore Personalize REST API allows developers to programmatically interact with Sitecore Personalize experiments, decisioning flows, connection configurations, and template assets. It supports retrieving, creating, updating, and deleting personalization resources through standard HTTP methods. Developers use this API to integrate decisioning logic into server-side applications, trigger personalization flows programmatically, manage personalization assets as part of automated deployment pipelines, and connect to external systems via configurable connection objects. The API base URL is environment-specific and is determined by the region of the Sitecore Personalize instance.
  version: v1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://api.boxever.com
  description: Sitecore Personalize Production Server
security:
- apiKeyAuth: []
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:
  schemas:
    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
    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
    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
    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
  parameters:
    resourceId:
      name: id
      in: path
      description: The unique identifier of the resource
      required: true
      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
    sortBy:
      name: sort
      in: query
      description: Field name and direction to sort results by (e.g., name:asc)
      required: false
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: Number of items to return per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  responses:
    Unauthorized:
      description: Authentication credentials are missing or 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'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication. Provide the API key in the Authorization header obtained from the Sitecore Personalize instance configuration.
externalDocs:
  description: Sitecore Personalize Developer Documentation
  url: https://doc.sitecore.com/personalize/en/developers/api/index-en.html