openapi: 3.0.2
info:
  title: A/B Testing API
  description: API powering the A/B Testing feature of Algolia.
  version: 1.0.0
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: X-Algolia-Application-Id
    apiKey:
      type: apiKey
      in: header
      name: X-Algolia-API-Key
  parameters:
    PathInPath:
      name: path
      in: path
      description: >-
        The path of the API endpoint to target, anything after the /1 needs to
        be specified.
      required: true
      schema:
        type: string
        example: /keys
    Parameters:
      name: parameters
      in: query
      description: Query parameters to be applied to the current query.
      schema:
        type: object
        additionalProperties: true
    Offset:
      in: query
      name: offset
      description: Position of the starting record. Used for paging. 0 is the first record.
      schema:
        type: integer
        default: 0
    Limit:
      in: query
      name: limit
      description: Number of records to return. Limit is the size of the page.
      schema:
        type: integer
        default: 10
    ID:
      in: path
      name: id
      description: The A/B test ID.
      required: true
      schema:
        type: integer
  schemas:
    ErrorBase:
      description: Error.
      type: object
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    abTestID:
      type: integer
      description: The A/B test ID.
    endAt:
      type: string
      description: End date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
    createdAt:
      type: string
      description: End date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
    name:
      type: string
      description: A/B test name.
    description:
      type: string
      description: The A/B test description.
    index:
      type: string
      description: The index performing the A/B test.
    count:
      description: The number of occurrences.
      type: integer
    trackedSearchCount:
      type: integer
      description: The number of tracked search click.
    trafficPercentage:
      type: integer
      description: The traffic perfecentage for the A/B test.
    variant:
      type: object
      additionalProperties: false
      properties:
        averageClickPosition:
          type: integer
          description: Average click position for the variant.
        clickCount:
          type: integer
          description: Distinct click count for the variant.
        clickThroughRate:
          type: number
          format: double
          description: Click through rate for the variant.
        conversionCount:
          type: integer
          description: Distinct conversion count for the variant.
        conversionRate:
          type: number
          format: double
          description: Conversion rate for the variant.
        description:
          $ref: '#/components/schemas/description'
        index:
          $ref: '#/components/schemas/index'
        noResultCount:
          $ref: '#/components/schemas/count'
        searchCount:
          type: integer
          description: The number of search during the A/B test.
        trackedSearchCount:
          $ref: '#/components/schemas/trackedSearchCount'
        trafficPercentage:
          $ref: '#/components/schemas/trafficPercentage'
        userCount:
          type: integer
          description: The number of user during the A/B test.
      required:
        - userCount
        - trafficPercentage
        - trackedSearchCount
        - searchCount
        - noResultCount
        - index
        - description
        - conversionRate
        - conversionCount
        - clickThroughRate
        - clickCount
        - averageClickPosition
    variants:
      type: array
      description: List of A/B test variant.
      items:
        $ref: '#/components/schemas/variant'
    ABTest:
      type: object
      additionalProperties: false
      properties:
        abTestID:
          $ref: '#/components/schemas/abTestID'
        clickSignificance:
          type: number
          format: double
          description: >-
            A/B test significance based on click data. Should be > 0.95 to be
            considered significant (no matter which variant is winning).
        conversionSignificance:
          type: number
          format: double
          description: >-
            A/B test significance based on conversion data. Should be > 0.95 to
            be considered significant (no matter which variant is winning).
        endAt:
          $ref: '#/components/schemas/endAt'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        name:
          $ref: '#/components/schemas/name'
        status:
          type: string
          description: status of the A/B test.
        variants:
          $ref: '#/components/schemas/variants'
      required:
        - status
        - name
        - createdAt
        - endAt
        - conversionSignificance
        - clickSignificance
        - abTestID
        - variants
    ABTests:
      type: array
      description: List of A/B tests.
      items:
        $ref: '#/components/schemas/ABTest'
    abTestsVariant:
      type: object
      additionalProperties: false
      properties:
        index:
          $ref: '#/components/schemas/index'
        trafficPercentage:
          $ref: '#/components/schemas/trafficPercentage'
        description:
          $ref: '#/components/schemas/description'
      required:
        - index
        - trafficPercentage
    customSearchParams:
      type: object
      additionalProperties: false
      properties:
        customSearchParameters:
          type: object
      required:
        - customSearchParameters
    abTestsVariantSearchParams:
      allOf:
        - $ref: '#/components/schemas/abTestsVariant'
        - $ref: '#/components/schemas/customSearchParams'
    AddABTestsVariant:
      oneOf:
        - $ref: '#/components/schemas/abTestsVariant'
        - $ref: '#/components/schemas/abTestsVariantSearchParams'
    taskID:
      type: integer
      format: int64
      description: taskID of the task to wait for.
    ABTestResponse:
      type: object
      additionalProperties: false
      properties:
        index:
          $ref: '#/components/schemas/index'
        abTestID:
          $ref: '#/components/schemas/abTestID'
        taskID:
          $ref: '#/components/schemas/taskID'
      required:
        - abTestID
        - index
        - taskID
  responses:
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
servers:
  - url: https://analytics.{region}.algolia.com
    variables:
      region:
        enum:
          - us
          - de
        default: us
  - url: https://analytics.algolia.com
security:
  - appId: []
    apiKey: []
tags:
  - name: abtest
    x-displayName: A/B Testing
    description: Manage A/B Tests.
x-tagGroups:
  - name: General
    tags:
      - abtest
paths:
  /1{path}:
    get:
      operationId: get
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
    post:
      operationId: post
      requestBody:
        description: The parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
    put:
      operationId: put
      requestBody:
        description: The parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
    delete:
      operationId: del
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
  /2/abtests:
    post:
      tags:
        - abtest
      operationId: addABTests
      summary: Create a test
      description: >
        Creates a new A/B test with provided configuration.

        You can set an A/B test on two different indices with different
        settings, or on the same index with different search parameters by
        providing a customSearchParameters setting on one of the variants.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: addABTestsRequest
              type: object
              additionalProperties: false
              properties:
                name:
                  $ref: '#/components/schemas/name'
                variant:
                  type: array
                  description: List of 2 variants for the A/B test.
                  minItems: 2
                  maxItems: 2
                  items:
                    $ref: '#/components/schemas/AddABTestsVariant'
                endAt:
                  $ref: '#/components/schemas/endAt'
              required:
                - name
                - variant
                - endAt
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ABTestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
    get:
      tags:
        - abtest
      operationId: listABTests
      summary: List all tests
      description: >
        Fetch all existing A/B tests for App that are available for the current
        API Key.

        When no data has been processed, the metrics will be returned as null.
      parameters:
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: listABTestsResponse
                type: object
                additionalProperties: false
                properties:
                  abtests:
                    $ref: '#/components/schemas/ABTests'
                  count:
                    type: integer
                    description: Number of A/B tests found for the app.
                  total:
                    type: integer
                    description: Number of A/B tests retrievable.
                required:
                  - abtests
                  - count
                  - total
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
  /2/abtests/{id}:
    get:
      tags:
        - abtest
      operationId: getABTest
      summary: Get a test
      description: |
        Returns metadata and metrics for an A/B test.
      parameters:
        - $ref: '#/components/parameters/ID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ABTest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
    delete:
      tags:
        - abtest
      operationId: deleteABTest
      summary: Delete a test
      description: Delete a test.
      parameters:
        - $ref: '#/components/parameters/ID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ABTestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
  /2/abtests/{id}/stop:
    post:
      tags:
        - abtest
      operationId: stopABTest
      summary: Stop a test
      description: >
        Marks the A/B test as stopped.

        At this point, the test is over and cannot be restarted. As a result,
        your application is back to normal: index A will perform as usual,
        receiving 100% of all search requests. Associated metadata and metrics
        are still stored.
      parameters:
        - $ref: '#/components/parameters/ID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ABTestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
