openapi: 3.0.2
info:
  title: Insights API
  summary: The Insights API lets you collect events related to your search and discovery experience
  description: |
    Events represent user interactions with your app or website.
    They unlock powerful features, such as recommendations, personalization, smarter search results,
    and analytics that help you optimize your user experience.

    ## Client libraries

    Use Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API.
    For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/libraries).

    ## Base URLs

    The base URLs for making requests to the Insights API are:

    - `https://insights.us.algolia.io`
    - `https://insights.de.algolia.io`
    - `https//insights.algolia.io` (routes requests to the closest of the above servers, based on your geographical location)

    **All requests must use HTTPS.**

    ## Authentication

    Add these headers to authenticate requests:

    - `x-algolia-application-id`. Your Algolia application ID.
    - `x-algolia-api-key`. An API key with the necessary permissions to make the request.
      The required access control list (ACL) to make a request is listed in each endpoint's reference.

    You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).

    ## Request format

    Request bodies must be JSON objects.

    ## Response status and errors

    Response bodies are JSON objects.
    Deleting a user token returns an empty response body with rate-limiting information as headers.

    Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
    Error responses have a `message` property with more information.

    The Insights API doesn't validate if the event parameters such as `indexName`, `objectIDs`, or `userToken`,
    correspond to anything in the Search API. It just checks if they're formatted correctly.
    Check the [Events](https://dashboard.algolia.com/events/health) health section,
    whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking.

    ## Version

    The current version of the Insights API is version 1, indicated by the `/1/` in each endpoint's URL.
  version: 1.0.0
externalDocs:
  url: https://www.algolia.com/doc/guides/sending-events/getting-started
  description: Events
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
servers:
  - url: https://insights.{region}.algolia.io
    variables:
      region:
        description: The region where your Algolia application is hosted.
        enum:
          - us
          - de
        default: us
  - url: https://insights.algolia.io
security:
  - appId: []
    apiKey: []
tags:
  - name: events
    x-displayName: Events
    description: >-
      Events represent user interactions with your website or app.
      They include details like the event's name, type, a timestamp, or a user token.
  - name: usertokens
    x-displayName: User tokens
    description: |
      Delete events related to a specific user token.
x-tagGroups:
  - name: General
    tags:
      - events
      - usertokens
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  /1/events:
    $ref: 'paths/pushEvents.yml'

  /1/usertokens/{userToken}:
    $ref: 'paths/deleteUserToken.yml'

  # ###############
  # ### Helpers ###
  # ###############
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'