split-evaluator-api-openapi.yml

openapi: 3.1.0
info:
  title: Split Evaluator API
  description: >-
    The Split Evaluator is an HTTP service that wraps Split SDKs to provide
    feature flag evaluation via a REST API. It enables applications that cannot
    directly embed an SDK to request treatment evaluations over HTTP, making it
    suitable for architectures where a centralized evaluation service is
    preferred. The Evaluator can be deployed as a standalone microservice that
    processes getTreatment calls and returns the appropriate treatments for
    given users and feature flags. Swagger documentation is available by default
    at the /api-docs endpoint.
  version: '1.0'
  contact:
    name: Split Support
    url: https://help.split.io
  termsOfService: https://www.split.io/terms-of-service/
externalDocs:
  description: Split Evaluator Documentation
  url: https://help.split.io/hc/en-us/articles/360020037072-Split-Evaluator
servers:
  - url: http://localhost:7548
    description: Default local Evaluator instance
tags:
  - name: Evaluation
    description: >-
      Endpoints for evaluating feature flags and retrieving treatment values
      for given keys and feature flag names.
  - name: Events
    description: >-
      Endpoints for tracking custom events used in experimentation and
      metrics measurement.
paths:
  /admin/ping:
    get:
      operationId: ping
      summary: Ping service
      description: >-
        Checks whether the Split Evaluator service is running. If the service
        is running, it responds with the text pong and HTTP status code 200.
      tags: []
      responses:
        '200':
          description: Service is running
          content:
            text/plain:
              schema:
                type: string
                example: pong
  /admin/version:
    get:
      operationId: getVersion
      summary: Get service version
      description: >-
        Returns the current version of the Split Evaluator service.
      tags: []
      responses:
        '200':
          description: Service version information
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: Version string of the running Evaluator
  /admin/healthcheck:
    get:
      operationId: healthCheck
      summary: Health check
      description: >-
        Checks that the Split Evaluator is connected to Split servers and
        ready to process evaluation requests. Returns 200 if everything is
        working as expected or 500 if there is an issue, along with a message
        explaining the status.
      tags: []
      responses:
        '200':
          description: Service is healthy and ready for evaluations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
        '500':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
  /client/get-treatment:
    get:
      operationId: getTreatment
      summary: Get treatment for a feature flag
      description: >-
        Evaluates a single feature flag for the given key and returns the
        treatment value. Optionally includes dynamic configuration associated
        with the treatment. This is the primary endpoint for feature flag
        evaluation.
      tags:
        - Evaluation
      parameters:
        - name: key
          in: query
          required: true
          description: >-
            The customer key to evaluate the feature flag against
          schema:
            type: string
        - name: split-name
          in: query
          required: true
          description: >-
            The name of the feature flag to evaluate
          schema:
            type: string
        - name: bucketing-key
          in: query
          description: >-
            Optional bucketing key used for consistent percentage-based
            treatment assignments
          schema:
            type: string
        - name: attributes
          in: query
          description: >-
            JSON string of attributes used in targeting rule evaluation
          schema:
            type: string
        - name: impressions-disabled
          in: query
          description: >-
            When set to true, disables impression logging for this evaluation
          schema:
            type: boolean
      responses:
        '200':
          description: Successful evaluation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatmentResult'
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during evaluation
    post:
      operationId: getTreatmentWithAttributes
      summary: Get treatment with attributes
      description: >-
        Evaluates a single feature flag for the given key with attributes
        passed in the request body. This is preferred over the GET method
        when attributes contain complex or large data structures.
      tags:
        - Evaluation
      parameters:
        - name: key
          in: query
          required: true
          description: The customer key to evaluate the feature flag against
          schema:
            type: string
        - name: split-name
          in: query
          required: true
          description: The name of the feature flag to evaluate
          schema:
            type: string
        - name: bucketing-key
          in: query
          description: Optional bucketing key for consistent assignments
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationAttributes'
      responses:
        '200':
          description: Successful evaluation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatmentResult'
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during evaluation
  /client/get-treatments:
    get:
      operationId: getTreatments
      summary: Get treatments for multiple feature flags
      description: >-
        Evaluates multiple feature flags for the given key in a single request
        and returns the treatment values for each. More efficient than making
        individual get-treatment calls.
      tags:
        - Evaluation
      parameters:
        - name: key
          in: query
          required: true
          description: The customer key to evaluate feature flags against
          schema:
            type: string
        - name: split-names
          in: query
          required: true
          description: >-
            Comma-separated list of feature flag names to evaluate
          schema:
            type: string
        - name: bucketing-key
          in: query
          description: Optional bucketing key for consistent assignments
          schema:
            type: string
        - name: attributes
          in: query
          description: JSON string of attributes for targeting rule evaluation
          schema:
            type: string
        - name: impressions-disabled
          in: query
          description: >-
            When set to true, disables impression logging for these evaluations
          schema:
            type: boolean
      responses:
        '200':
          description: Successful evaluation response with multiple treatments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatmentsResult'
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during evaluation
    post:
      operationId: getTreatmentsWithAttributes
      summary: Get treatments with attributes
      description: >-
        Evaluates multiple feature flags for the given key with attributes
        passed in the request body.
      tags:
        - Evaluation
      parameters:
        - name: key
          in: query
          required: true
          description: The customer key to evaluate feature flags against
          schema:
            type: string
        - name: split-names
          in: query
          required: true
          description: Comma-separated list of feature flag names to evaluate
          schema:
            type: string
        - name: bucketing-key
          in: query
          description: Optional bucketing key for consistent assignments
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationAttributes'
      responses:
        '200':
          description: Successful evaluation response with multiple treatments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatmentsResult'
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during evaluation
  /client/get-all-treatments:
    get:
      operationId: getAllTreatments
      summary: Get all treatments for a key
      description: >-
        Evaluates all available feature flags for the given keys and traffic
        types and returns the treatment values. Useful for retrieving a
        complete set of flag evaluations for a user session.
      tags:
        - Evaluation
      parameters:
        - name: keys
          in: query
          required: true
          description: >-
            JSON string containing an array of key objects with matchingKey
            and trafficType properties, and optionally a bucketingKey
          schema:
            type: string
        - name: attributes
          in: query
          description: JSON string of attributes for targeting rule evaluation
          schema:
            type: string
        - name: impressions-disabled
          in: query
          description: >-
            When set to true, disables impression logging for these evaluations
          schema:
            type: boolean
      responses:
        '200':
          description: >-
            Successful response with treatments for all feature flags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllTreatmentsResult'
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during evaluation
    post:
      operationId: getAllTreatmentsWithAttributes
      summary: Get all treatments with attributes
      description: >-
        Evaluates all available feature flags for the given keys with
        attributes passed in the request body.
      tags:
        - Evaluation
      parameters:
        - name: keys
          in: query
          required: true
          description: >-
            JSON string containing an array of key objects
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationAttributes'
      responses:
        '200':
          description: >-
            Successful response with treatments for all feature flags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllTreatmentsResult'
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during evaluation
  /client/track:
    get:
      operationId: trackEvent
      summary: Track an event
      description: >-
        Records a custom event for the given key and event type. Events are
        used to measure the impact of feature flags on user actions and
        experimentation metrics.
      tags:
        - Events
      parameters:
        - name: key
          in: query
          required: true
          description: The customer key associated with the event
          schema:
            type: string
        - name: traffic-type
          in: query
          required: true
          description: The traffic type for the event
          schema:
            type: string
        - name: event-type
          in: query
          required: true
          description: >-
            The type of event being tracked (e.g., purchase, click, signup)
          schema:
            type: string
        - name: value
          in: query
          description: Optional numeric value associated with the event
          schema:
            type: number
        - name: properties
          in: query
          description: >-
            JSON string with up to 15 key-value pairs of event properties.
            Values must be boolean, string, number, or null.
          schema:
            type: string
      responses:
        '200':
          description: Event tracked successfully
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during tracking
    post:
      operationId: trackEventWithProperties
      summary: Track an event with properties
      description: >-
        Records a custom event with properties passed in the request body.
        Preferred for events with complex property structures.
      tags:
        - Events
      parameters:
        - name: key
          in: query
          required: true
          description: The customer key associated with the event
          schema:
            type: string
        - name: traffic-type
          in: query
          required: true
          description: The traffic type for the event
          schema:
            type: string
        - name: event-type
          in: query
          required: true
          description: The type of event being tracked
          schema:
            type: string
        - name: value
          in: query
          description: Optional numeric value associated with the event
          schema:
            type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventProperties'
      responses:
        '200':
          description: Event tracked successfully
        '400':
          description: Missing or invalid parameters
        '500':
          description: Internal server error during tracking
components:
  schemas:
    HealthCheckResponse:
      type: object
      description: Health check response from the Split Evaluator
      properties:
        status:
          type: string
          description: Health status of the service
          enum:
            - ok
            - error
        message:
          type: string
          description: Detailed message about the health status
    TreatmentResult:
      type: object
      description: >-
        The result of evaluating a single feature flag for a given key.
      properties:
        splitName:
          type: string
          description: Name of the evaluated feature flag
        treatment:
          type: string
          description: >-
            The treatment value returned by the evaluation (e.g., on, off)
        config:
          type: string
          nullable: true
          description: >-
            JSON string of dynamic configuration associated with the
            treatment, or null if no configuration is defined
    TreatmentsResult:
      type: object
      description: >-
        The result of evaluating multiple feature flags for a given key.
        Keys are feature flag names and values are treatment results.
      additionalProperties:
        $ref: '#/components/schemas/TreatmentResult'
    AllTreatmentsResult:
      type: object
      description: >-
        The result of evaluating all feature flags for the given keys. Keyed
        by feature flag name with treatment result values.
      additionalProperties:
        $ref: '#/components/schemas/TreatmentResult'
    EvaluationAttributes:
      type: object
      description: >-
        Attributes passed in the request body for use in targeting rule
        evaluation. Attributes can be strings, numbers, booleans, or sets.
      properties:
        attributes:
          type: object
          description: Key-value pairs of attribute names and their values
          additionalProperties: true
        impressionsDisabled:
          type: boolean
          description: >-
            When set to true, disables impression logging for the evaluation
    EventProperties:
      type: object
      description: >-
        Properties associated with a tracked event.
      properties:
        properties:
          type: object
          description: >-
            Key-value pairs of event properties. Maximum 15 keys. Values
            must be boolean, string, number, or null.
          additionalProperties: true
          maxProperties: 15