openapi: 3.0.0
info:
  title: Optimizely Agent API
  description: Optimizely Agent is a stand-alone, open-source microservice that provides major benefits over using Optimizely SDKs in certain use cases. Its REST API offers consolidated and simplified endpoints for accessing all the functionality of Optimizely Feature Experimentation SDKs. Use this API the control experiments (such as a feature tests). For more info, see https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/optimizely-agent
  termsOfService: https://www.optimizely.com/legal/terms/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.12.0
security:
  - SdkKeyAuth: []
  - TokenAuth: []
paths:
  /v1/config:
    get:
      summary: Return the Optimizely config for the given environment
      operationId: getConfig
      description: Return all available experiment and features definitions for this environment.
      responses:
        '200':
          description: Valid response
          content:
            application/json:
              schema:
                description: Optimizely Configuration
                $ref: '#/components/schemas/OptimizelyConfig'
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/datafile:
    get:
      summary: >-
        Return the datafile for the given environment. If you need strict consistency, you can pass the datafile to other Optimizely instances. 
        so that all initialize from exactly the same datafile version (rather than each fetching the datafile separately from the Optimizely CDN).  
      operationId: getDatafile
      description: Returns the json datafile for the given environment.
      responses:
        '200':
          description: Valid response
          content:
            application/json:
              schema:
                description: Optimizely Datafile
                type: object
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/decide:
    parameters:
      - $ref: '#/components/parameters/decideKeysParam'
    post:
      summary: Decide makes feature decisions for the selected query parameters.
      operationId: decide
      description: >-
        Returns decision results for flag keys for a user.
        The result for a single key is returned as an
        OptimizelyDecision object whereas the result for multiple keys is returned as an array of OptimizelyDecision objects. If no flag key is
        provided, decision is made for all flag keys. OptimizelyDecision object
        contains all data required to deliver the flag rule.
      requestBody:
        $ref: '#/components/requestBodies/DecideContext'
      responses:
        '200':
          description: Valid response
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/OptimizelyDecision'
                  - $ref: '#/components/schemas/OptimizelyDecision'
        '400':
          description: Missing required parameters
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: 'Failed to fetch qualified segments'
  /v1/lookup:
    post:
      summary: Lookup returns saved user profile.
      operationId: lookup
      description: >-
        Returns the saved user profile for a user.
      requestBody:
        $ref: '#/components/requestBodies/LookupContext'
      responses:
        '200':
          description: Valid response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          description: Missing required parameters
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: User Profile Service not found
  /v1/save:
    post:
      summary: Save saves user profile.
      operationId: save
      description: >-
        Saves user profile for a user.
      requestBody:
        $ref: '#/components/requestBodies/SaveContext'
      responses:
        '200':
          description: Valid response, Profile saved.
        '400':
          description: Missing required parameters
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: User Profile Service not found
  /v1/track:
    parameters:
      - $ref: '#/components/parameters/eventKeyParam'
    post:
      summary: Track event for the given user.
      operationId: trackEvent
      description: Send event and user details to Optimizely analytics backend, so you can see metrics for an experiment. You can view metrics either on your Results page or as a data export.
      responses:
        '200':
          description: Valid response, event received
        '400':
          description: Missing required parameters
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
      requestBody:
        $ref: '#/components/requestBodies/TrackContext'
  /v1/send-odp-event:
    post:
      summary: Send event to Optimizely Data Platform (ODP).
      operationId: sendOdpEvent
      description: Send ODP event to Optimizely Data Platform. Clients can send arbitrary events to the ODP server. For instance, they can bind an email to the FS userId via this API.
      responses:
        '200':
          description: Valid response, event received
        '400':
          description: Missing required parameters
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: 'Failed to send odp event'
      requestBody:
        $ref: '#/components/requestBodies/SendOdpEventContext'
  /v1/activate:
    parameters:
      - $ref: '#/components/parameters/featureKeyParam'
      - $ref: '#/components/parameters/experimentKeyParam'
      - $ref: '#/components/parameters/disableTrackingParam'
      - $ref: '#/components/parameters/typeParam'
      - $ref: '#/components/parameters/enabledParam'
    post:
      summary: Activate selected features and experiments for the given user.
      operationId: activate
      description: Returns Optimizely's decision about which features and experiments a given user is exposed to. Optionally sends an impression event to the Optimizely analytics backend for any decision made for an experiment. This endpoint consolidates key functionality from the Feature Experimentation SDKs into one convenient call.
      responses:
        '200':
          description: Valid response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Decision'
        '400':
          description: Bad request, invalid parameters
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
      requestBody:
        $ref: '#/components/requestBodies/ActivateContext'
  /v1/override:
    post:
      summary: Override an experiment decision for a user
      operationId: override
      description: For debugging or testing. Overrides an experiment and variation decision for a given user, in local memory only. Do not use this endpoint for production overrides.
      responses:
        '200':
          description: Valid response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Override'
        '400':
          description: Invalid payload
        '401':
          description: Unauthorized, invalid JWT
        '403':
          $ref: '#/components/responses/Forbidden'
      requestBody:
        $ref: '#/components/requestBodies/OverrideContext'
  /oauth/token:
    post:
      summary: Get JWT token to authenticate all requests.
      operationId: getToken
      description: Generates valid JWT token for grant_type, client_id, and client_secret, using the values you pass in the request body.  Configure expiration time and SDK keys (to which the token grants access) in Optimizely config. 
      responses:
        '200':
          description: Generates a valid token
        '401':
          description: Unauthorized, invalid values for parameter(s)
          $ref: '#/components/responses/UnauthorizedToken'
      requestBody:
        $ref: '#/components/requestBodies/TokenContext'
  /v1/batch:
    post:
      summary: Batch multiple API endpoints into one request.
      description:  |
                      You can use the Batch endpoint to do things like   
                      1. Make activate decisions for a batch of users in a short timeframe for testing purposes
                      2. Gather responses from a bunch of activate calls into one response for comparison or analysis
      responses:  

        '200':
          $ref: '#/components/responses/BatchResponse'
        '400':
          description: Bad request, invalid parameters.
        '422':
          description: Unprocessable Entity, too many operations
      requestBody:
        $ref: '#/components/requestBodies/BatchContext'

components:
  parameters:
    disableTrackingParam:
      in: query
      name: disableTracking
      required: false
      description: Setting to true will disable impression tracking for experiments.
      schema:
        type: boolean
    enabledParam:
      in: query
      name: enabled
      required: false
      description: Filter the activation response to return only enabled descisions.
      schema:
        type: boolean
    eventKeyParam:
      in: query
      name: eventKey
      required: true
      description: Key of the event we're tracking
      schema:
        type: string
    decideKeysParam:
      in: query
      name: keys
      required: false
      description: Flag keys for decision
      schema:
        type: string
    experimentKeyParam:
      in: query
      name: experimentKey
      description: Key for the Optimizely Experiment
      schema:
        type: array
        items:
          type: string
    featureKeyParam:
      in: query
      name: featureKey
      description: Key for the Optimizely Feature
      schema:
        type: array
        items:
          type: string
    typeParam:
      in: query
      name: type
      required: false
      description: Limit the decisions to either experiment or features
      schema:
        type: string
        enum:
          - feature
          - experiment
  requestBodies:
    ActivateContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActivateContext'
    OverrideContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OverrideContext'
    TrackContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrackContext'
    SendOdpEventContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendOdpEventContext'
    LookupContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupContext'
    SaveContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SaveContext'
    DecideContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DecideContext'
    TokenContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenContext'
    BatchContext:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BatchContext'           
  responses:
    Forbidden:
      description: You do not have necessary permissions for the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedToken:
      description: Unable to match credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenError'
    BatchResponse:
      description: responses for each endpoint called in the batch request
      content:
        application/json:
         schema:
          $ref: '#/components/schemas/BatchResponse'    
  schemas:
    Error:
      properties:
        error:
          type: string
    TokenError:
      properties:
        error:
          type: string
        error_description:
          type: string
    OptimizelyExperiment:
      properties:
        id:
          type: string
        key:
          type: string
        audiences:
          type: string
        variationsMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OptimizelyVariation'
      required:
        - id
        - key
    OptimizelyAttribute:
      properties:
        id:
          type: string
        key:
          type: string
    OptimizelyAudience:
      properties:
        id:
          type: string
        name:
          type: string
        conditions:
          type: string
    OptimizelyEvent:
      properties:
        id:
          type: string
        key:
          type: string
        experimentIds:
          type: array
          items:
            type: string
    OptimizelyFeature:
      properties:
        id:
          type: string
        key:
          type: string
        experimentRules:
          type: array
          items:
            $ref: '#/components/schemas/OptimizelyExperiment'
        deliveryRules:
          type: array
          items:
            $ref: '#/components/schemas/OptimizelyExperiment'
        variablesMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OptimizelyVariable'
        experimentsMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OptimizelyExperiment'
      required:
        - id
        - key
    UserProfile:
      properties:
        experimentBucketMap:
          type: object
          properties:
            your_experiment_id:
              type: object
              properties:
                variation_id:
                  type: string
        userId:
          type: string
    Decision:
      properties:
        featureKey:
          type: string
        experimentKey:
          type: string
        variationKey:
          type: string
        type:
          type: string
          enum:
            - feature
            - experiment
            - ''
        enabled:
          type: boolean
        variables:
          type: object
          additionalProperties: true
        error:
          type: string
    OptimizelyDecision:
      properties:
        variables:
          type: object
        variationKey:
          type: string
        enabled:
          type: boolean
        ruleKey:
          type: string
        flagKey:
          type: string
        userContext:
          type: object
          properties:
            userId:
              type: string
            attributes:
              type: object
              additionalProperties: true
          required:
            - userId
        reasons:
          type: array
          items:
            type: string
      required:
        - ruleKey
        - flagKey
        - userContext
    ActivateContext:
      properties:
        userId:
          type: string
        userAttributes:
          type: object
          additionalProperties: true
    Override:
      properties:
        userId:
          type: string
        experimentKey:
          type: string
        variationKey:
          type: string
        prevVariationKey:
          type: string
        messages:
          type: array
          items:
            type: string
    OverrideContext:
        type: object
        properties:
          userId:
            type: string
          experimentKey:
            type: string
          variationKey:
            type: string
    OptimizelyConfig:
      properties:
        environmentKey:
          type: string
        sdkKey:
          type: string
        revision:
          type: string
        experimentsMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OptimizelyExperiment'
        featuresMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OptimizelyFeature'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OptimizelyAttribute'
        audiences:
          type: array
          items:
            $ref: '#/components/schemas/OptimizelyAudience'
        events:
          type: array
          items:
            $ref: '#/components/schemas/OptimizelyEvent'
    TrackContext:
      properties:
        eventTags:
          type: object
          additionalProperties: true
        userId:
          type: string
        userAttributes:
          type: object
          additionalProperties: true
    SendOdpEventContext:
      properties:
        action:
          type: string
        type:
          type: string
        identifiers:
          type: object
          additionalProperties:
            type: string
        data:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
      required:
        - action
        - identifiers
    LookupContext:
      properties:
        userId:
          type: string
      required:
        - userId
    SaveContext:
      $ref: '#/components/schemas/UserProfile'
    DecideContext:
      properties:
        decideOptions:
          type: array
          items:
            type: string
            enum:
              - DISABLE_DECISION_EVENT
              - ENABLED_FLAGS_ONLY
              - IGNORE_USER_PROFILE_SERVICE
              - EXCLUDE_VARIABLES
              - INCLUDE_REASONS
        userId:
          type: string
        userAttributes:
          type: object
          additionalProperties: true
        forcedDecisions:
          type: array
          items:
            $ref: '#/components/schemas/ForcedDecision'
        fetchSegments:
          type: boolean
        fetchSegmentsOptions:
          type: array
          items:
            type: string
            enum:
              - IGNORE_CACHE
              - RESET_CACHE
      required:
        - userId
    ForcedDecision:
      properties:
        flagKey:
          type: string
        ruleKey:
          type: string
        variationKey:
          type: string
      required:
        - flagKey
        - variationKey
    OptimizelyVariation:
      properties:
        id:
          type: string
        key:
          type: string
        featureEnabled:
          type: boolean
        variablesMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OptimizelyVariable'
      required:
        - id
        - key
    OptimizelyVariable:
      properties:
        id:
          type: string
        key:
          type: string
        type:
          type: string
        value:
          type: string
      required:
        - id
        - key
    TokenContext:
      properties:
        grant_type:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
    BatchContext:
      properties:
        operations:
          description: Array of requests to Agent endpoints, batched into one request
          type: array
          items:
            $ref: '#/components/schemas/BatchOperation'
      required:
        - operations

    BatchOperation:
      properties:
        method:
          description: The REST request method
          type: string
          enum:
            - GET
            - POST
        url:
          description: The base and endpoint components of the API request's path
          type: string
        operationID: 
          description: Index of the request in the batch  
          type: string
        body:
          description: The body for the request as JSON
          type: object
        parameters:
          description: The parameters for the request as JSON
          type: object
        headers:
          description: The headers for the request as JSON
          type: object
      example:   
        method: "POST"
        url: "/v1/activate"
        operationID: 1
        body: {"userId": "user1"}
        parameters: {
          "type": "feature",
          "experimentKey": "ab_test_experiment"}
        headers: {
          "X-Optimizely-SDK-Key": "<sdk_key>",
          "Content-Type": "application/json"}  

    BatchResponse:
      properties:
        startedAt:
          type: string
        endedAt:
          type: string 
        errorCount:
          type: integer
        response:
          type: array
          items:
            $ref: '#/components/schemas/BatchResponseItem'  

    BatchResponseItem:
      properties:
        status:
          type: integer
          enum:
            - 200 
            - 400
        requestID:
          type: string
        operationID:
          type: string
        method:
          type: string
          enum:
            - GET
            - POST
        url:
          type: string
        body:
          oneOf:
            - type: array
              items:
                type: object
            - type: object
        startedAt:
          type: string
        endedAt:
          type: string

      example: 
        status: 200
        requestID: "abee6bdf-6d14-4fac-8357-769f5fd07e7c"
        operationID: "1"
        method: POST
        url: "/v1/activate"
        body:  [
        {
          "enabled": true,
          "experimentKey": "new_feature_test",
          "featureKey": "new_feature",
          "type": "feature",
          "userId": "user1",
          "variables": {
            "bool_var": true,
            "double_var": 5.6,
            "int_var": 1,
          },
          "variationKey": "variation_2"
        },

        {
          "enabled": false,
          "experimentKey": "flag_test_2",
          "featureKey": "test_feature",
          "type": "feature",
          "userId": "user1",
          "variables": {
            "double": 0,
            "json_key": {}
          },
          "variationKey": ""
        }
        ]

        startedAt: "2020-09-10T10:50:37.466121-07:00"
        endedAt: "2020-09-10T10:50:37.466192-07:00"

  securitySchemes:
     SdkKeyAuth:
       in: header
       name: X-Optimizely-SDK-Key
       type: apiKey
     TokenAuth:
       type: http
       scheme: bearer
       bearerFormat: JWT