sitecore Connections API

openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Connections 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: 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:
  schemas:
    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
    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
    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
    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
  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'
  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