sitecore Events API

openapi: 3.2.0
info:
  title: Sitecore Discover Events API
  description: The Sitecore Discover API provides search and product discovery capabilities for commerce applications, enabling developers to build search experiences, product listing pages, and recommendation widgets. It exposes endpoints for full-text search, faceted filtering, product recommendations, behavioral event tracking, and incremental product feed updates. The Search and Recommendation API accepts requests as JSON and returns ranked results. Events sent through the Events API feed behavioral signals back into the discovery algorithms to improve recommendation relevance. The Incremental Feed API enables real-time product catalog updates. Endpoint URLs are customer-specific and contain either a subdomain URL or customer key retrieved from the Sitecore Discover Customer Engagement Console.
  version: v3
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://{subdomain}.rfksrv.com
  description: Sitecore Discover Production Server (subdomain URL)
  variables:
    subdomain:
      description: The customer-specific subdomain provided in the Discover CEC
      default: your-domain
- url: https://api.rfksrv.com
  description: Sitecore Discover Production Server (customer key URL)
security:
- bearerAuth: []
tags:
- name: Events
  description: Endpoints for sending behavioral and interaction events from storefronts to Sitecore Discover. Events include clicks, purchases, and page views that improve recommendation relevance over time.
paths:
  /api/event/1:
    get:
      operationId: trackEventGet
      summary: Track a behavioral event (GET)
      description: Sends a behavioral event from a storefront visitor session to Sitecore Discover. Events are used to improve the relevance of search results and product recommendations. The key parameter contains a URL-encoded JSON object with the event details.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/customerKey'
      - name: key
        in: query
        description: URL-encoded JSON object containing event details
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Event tracked successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: trackEventPost
      summary: Track a behavioral event (POST)
      description: Sends one or more behavioral events from a storefront visitor session using a POST request body. Events are used to improve search and recommendation relevance over time.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/customerKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
      responses:
        '200':
          description: Event tracked successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    customerKey:
      name: customerKey
      in: query
      description: The customer key identifying the Sitecore Discover account. Found in the Customer Engagement Console under Developer Resources > API Access.
      required: false
      schema:
        type: string
  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
    EventRequest:
      type: object
      description: Behavioral event tracking request
      required:
      - data
      properties:
        data:
          type: array
          description: List of behavioral events to track
          items:
            $ref: '#/components/schemas/BehavioralEvent'
    BehavioralEvent:
      type: object
      description: A single behavioral event from a storefront visitor
      required:
      - type
      properties:
        type:
          type: string
          description: The type of behavioral event
          enum:
          - click
          - purchase
          - view
          - search
          - addToCart
          - removeFromCart
          - impression
        sku:
          type: string
          description: The product SKU involved in the event
        price:
          type: number
          description: The price of the product at time of the event
          format: float
        quantity:
          type: integer
          description: The quantity involved in the event
        orderId:
          type: string
          description: The order identifier for purchase events
        pageType:
          type: string
          description: The type of page where the event occurred
          enum:
          - home
          - search
          - plp
          - pdp
          - cart
          - order-confirm
          - other
  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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer access token obtained from the Sitecore Discover authentication endpoint. Include in the Authorization header.
externalDocs:
  description: Sitecore Discover Developer Guide
  url: https://doc.sitecore.com/discover/en/developers/discover-developer-guide/integrate-using-discover-rest-apis.html