sitecore Connections API

openapi: 3.2.0
info:
  title: Sitecore Personalize REST Connections 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: Connections
  description: Endpoints for creating, retrieving, updating, and testing connections to external systems used in personalization flows and decision models. Connections define authentication credentials and URL configurations for external services.
paths:
  /v1/connections:
    get:
      operationId: listConnections
      summary: List connections
      description: Retrieves a paginated collection of all connections configured in the Sitecore Personalize instance. Connections represent integrations with external systems used within decision models and personalization flows. Supports search, sorting, and pagination via query parameters.
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageOffset'
      - $ref: '#/components/parameters/sortBy'
      responses:
        '200':
          description: A paginated list of connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createConnection
      summary: Create a connection
      description: Creates a new connection to an external system. Connections define the authentication type, endpoint URL, request configuration, and field mappings used when calling the external service from within a personalization flow or decision model.
      tags:
      - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequest'
      responses:
        '201':
          description: Connection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/connections/{id}:
    get:
      operationId: getConnection
      summary: Get a connection
      description: Retrieves a specific connection by its unique identifier. Returns the full connection configuration including authentication settings, URL, and field mappings.
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Connection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateConnection
      summary: Update a connection
      description: Performs a full replacement update of a connection. All fields are replaced with the values provided in the request body.
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequest'
      responses:
        '200':
          description: Connection updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/connections/{id}/test:
    post:
      operationId: testConnection
      summary: Test a connection
      description: Performs a test call to the external system using the connection configuration to verify that the credentials and endpoint URL are correct and the service is reachable.
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Connection test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionTestResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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
  schemas:
    Connection:
      type: object
      description: A connection to an external system used within Sitecore Personalize decision models and flows
      properties:
        ref:
          type: string
          description: The unique identifier of the connection
        name:
          type: string
          description: The display name of the connection
        description:
          type: string
          description: A description of what the connection is used for
        authType:
          type: string
          description: The authentication method used by the connection
          enum:
          - NONE
          - BASIC
          - OAUTH
          - API_KEY
        connectionUrl:
          type: string
          description: The URL of the external service endpoint
          format: uri
        requestType:
          type: string
          description: The HTTP method used for requests
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
        connectionTimeout:
          type: integer
          description: Timeout in milliseconds before aborting the connection
        socketTimeout:
          type: integer
          description: Timeout in milliseconds waiting for response data
        createdAt:
          type: string
          description: The ISO 8601 timestamp when the connection was created
          format: date-time
        modifiedAt:
          type: string
          description: The ISO 8601 timestamp when the connection 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
    ConnectionTestResult:
      type: object
      description: Result of a connection test
      properties:
        success:
          type: boolean
          description: Whether the connection test succeeded
        statusCode:
          type: integer
          description: The HTTP status code returned by the external service
        message:
          type: string
          description: A description of the test result or error
    ConnectionListResponse:
      type: object
      description: A paginated list of connections
      properties:
        items:
          type: array
          description: The connections for the current page
          items:
            $ref: '#/components/schemas/Connection'
        total:
          type: integer
          description: Total number of connections
    CreateConnectionRequest:
      type: object
      description: Request body for creating or updating a connection
      required:
      - name
      - connectionUrl
      - requestType
      properties:
        name:
          type: string
          description: The display name of the connection
        description:
          type: string
          description: A description of what the connection is used for
        authType:
          type: string
          description: The authentication method
          enum:
          - NONE
          - BASIC
          - OAUTH
          - API_KEY
        connectionUrl:
          type: string
          description: The URL of the external service endpoint
          format: uri
        requestType:
          type: string
          description: The HTTP method for requests
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
        connectionTimeout:
          type: integer
          description: Timeout in milliseconds before aborting the connection
        socketTimeout:
          type: integer
          description: Timeout in milliseconds waiting for response data
  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