Optimizely Rulesets API

openapi: 3.2.0
info:
  title: Optimizely Rulesets API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Rulesets across 2 of this provider''s published API definitions: optimizely-feature-experimentation-openapi.yml, optimizely-feature-experimentation-optimizely-feature-experimentation-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.optimizely.com/v2
  description: Optimizely REST API v2 Management Server
- url: https://api.optimizely.com/flags/v1
  description: Optimizely Flags API v1 Server
- url: https://api.optimizely.com/flags/v1/
tags:
- name: Rulesets
  description: Manage rulesets that define which variation a flag delivers to visitors within a given environment.
paths:
  /projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset:
    get:
      operationId: getRuleset
      summary: Get a ruleset
      description: Retrieves the ruleset for a specific flag in a given environment. A ruleset is the collection of rules that determine which variation a flag delivers to visitors.
      tags:
      - Rulesets
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      - $ref: '#/components/parameters/environmentKey'
      responses:
        '200':
          description: Successfully retrieved the ruleset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ruleset'
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag or environment not found
      security:
      - bearerAuth: []
    patch:
      operationId: updateRuleset
      summary: Update a ruleset
      description: Updates the ruleset for a specific flag in a given environment.
      tags:
      - Rulesets
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      - $ref: '#/components/parameters/environmentKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RulesetInput'
      responses:
        '200':
          description: Ruleset successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ruleset'
        '400':
          description: Invalid request body
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag or environment not found
      security:
      - bearerAuth: []
    parameters:
    - $ref: '#/components/parameters/projectId_2'
    - $ref: '#/components/parameters/flagKey_2'
    - $ref: '#/components/parameters/environmentKey_2'
    servers:
    - url: https://api.optimizely.com/v2
      description: Optimizely REST API v2 Management Server
    - url: https://api.optimizely.com/flags/v1
      description: Optimizely Flags API v1 Server
  /projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/enabled:
    post:
      operationId: enableRuleset
      summary: Enable a ruleset
      description: Enables the ruleset for a specific flag in a given environment, making the flag active and delivering variations to visitors.
      tags:
      - Rulesets
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      - $ref: '#/components/parameters/environmentKey'
      responses:
        '200':
          description: Ruleset successfully enabled
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag or environment not found
      security:
      - bearerAuth: []
    servers:
    - url: https://api.optimizely.com/v2
      description: Optimizely REST API v2 Management Server
    - url: https://api.optimizely.com/flags/v1
      description: Optimizely Flags API v1 Server
  /projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/disabled:
    post:
      operationId: disableRuleset
      summary: Disable a ruleset
      description: Disables the ruleset for a specific flag in a given environment, stopping the flag from delivering variations to visitors.
      tags:
      - Rulesets
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      - $ref: '#/components/parameters/environmentKey'
      responses:
        '200':
          description: Ruleset successfully disabled
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag or environment not found
      security:
      - bearerAuth: []
    servers:
    - url: https://api.optimizely.com/v2
      description: Optimizely REST API v2 Management Server
    - url: https://api.optimizely.com/flags/v1
      description: Optimizely Flags API v1 Server
components:
  parameters:
    flagKey:
      name: flag_key
      in: path
      required: true
      description: The unique key for the feature flag
      schema:
        type: string
    projectId:
      name: project_id
      in: path
      required: true
      description: The unique identifier for the project
      schema:
        type: integer
        format: int64
    environmentKey:
      name: environment_key
      in: path
      required: true
      description: The unique key for the environment
      schema:
        type: string
    flagKey_2:
      description: The Flag identifier
      example: recurring_deposit
      in: path
      name: flag_key
      required: true
      schema:
        type: string
    projectId_2:
      description: The project identifier
      example: 12345
      in: path
      name: project_id
      required: true
      schema:
        type: integer
    environmentKey_2:
      description: The Environment identifier
      example: production
      in: path
      name: environment_key
      required: true
      schema:
        type: string
  schemas:
    RulesetInput:
      type: object
      description: Input for updating a ruleset
      properties:
        rules:
          type: array
          description: Ordered list of rules in the ruleset
          items:
            $ref: '#/components/schemas/RuleInput'
    Ruleset:
      type: object
      description: A collection of rules that determine flag variation delivery
      properties:
        rules:
          type: array
          description: Ordered list of rules in the ruleset
          items:
            $ref: '#/components/schemas/Rule'
    Rule:
      type: object
      description: A rule that determines which variation to deliver
      properties:
        id:
          type: string
          description: Unique identifier for the rule
        key:
          type: string
          description: Unique key for the rule
        type:
          type: string
          description: Type of rule
          enum:
          - a/b_test
          - targeted_delivery
          - personalization
        audience_conditions:
          type: string
          description: JSON-encoded audience conditions for this rule
        percentage_included:
          type: integer
          description: Percentage of traffic included in this rule
          minimum: 0
          maximum: 10000
        variations:
          type: array
          description: Variations and their traffic allocation
          items:
            type: object
            properties:
              variation_key:
                type: string
                description: Key of the variation
              weight:
                type: integer
                description: Traffic weight for this variation
                minimum: 0
                maximum: 10000
    RuleInput:
      type: object
      description: Input for creating or updating a rule
      properties:
        key:
          type: string
          description: Unique key for the rule
        type:
          type: string
          description: Type of rule
          enum:
          - a/b_test
          - targeted_delivery
          - personalization
        audience_conditions:
          type: string
          description: JSON-encoded audience conditions
        percentage_included:
          type: integer
          description: Percentage of traffic included
          minimum: 0
          maximum: 10000
        variations:
          type: array
          description: Variations and their traffic allocation
          items:
            type: object
            properties:
              variation_key:
                type: string
                description: Key of the variation
              weight:
                type: integer
                description: Traffic weight
                minimum: 0
                maximum: 10000
    EventPropertyCondition:
      properties:
        name:
          type: string
        operator:
          enum:
          - equal_to
          - not_equal_to
          - greater_than
          - greater_than_or_equal_to
          - less_than
          - less_than_or_equal_to
          - contains
          - does_not_contain
          type: string
        type:
          enum:
          - string
          - number
          - boolean
          type: string
        value:
          type: string
      required:
      - name
      - type
      - value
      - operator
      type: object
    RuleGroupRule:
      example:
        id: 73915
        name: My Group
        traffic_allocation: 5000
      properties:
        group_id:
          description: Group id
          type: integer
        group_name:
          description: Name of the Group
          readOnly: true
          type: string
        traffic_allocation:
          description: The traffic allocation for the GroupRule
          maximum: 10000
          minimum: 0
          type: integer
      required:
      - group_id
      type: object
    SubMetric:
      properties:
        aggregator:
          type: string
        event_id:
          type: integer
        event_type:
          type: string
        field:
          type:
          - string
          - 'null'
        role:
          enum:
          - numerator
          - denominator
          type: string
        scope:
          type: string
      type: object
    AudienceConditionsString:
      description: A valid AudienceConditionsArray represented as a JSON string
      example: "[\n  \"or\",\n  {\n    \"audience_id\": 1038980040\n  },\n  {\n    \"audience_id\": 1033280055\n  },\n  [\n    \"not\",\n    {\n      \"audience_id\": 1120870079\n    }\n  ]\n]"
      type: string
    RuleAllowList:
      example:
        user_id: xyz123
        variation:
          key: false
          name: false
      properties:
        user_id:
          description: User identifier
          type: string
        variation:
          description: Variations to be added to user (key and name)
          properties:
            key:
              type: string
            name:
              type: string
          type: object
      required:
      - user_id
      - variation
      type: object
    ProblemDetail:
      additionalProperties: true
      description: https://tools.ietf.org/html/rfc7807#section-3.1
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        status:
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        type:
          description: A URI reference [RFC3986] that identifies the problem type. Contains 'about:blank' if unspecified.
          type: string
        uuid:
          description: Error reference for customer support
          type: string
      required:
      - detail
      - status
      - title
      - type
      type: object
    AudienceConditionsArray:
      example:
      - or
      - audience_id: 123
      - - and
        - audience_id: 456
        - audience_id: 789
      items:
        anyOf:
        - description: The logical operator to use (e.g. "and", "or", or "not"). This must be the first item in the audience_conditions array. The "not" operator may only be used in conjunction with a single condition or list.
          type: string
        - description: An invidual conditional, consisting of a JSON object with an "audience_id" value.
          properties:
            audience_id:
              type: integer
          required:
          - audience_id
          type: object
        - $ref: '#/components/schemas/AudienceConditionsArray'
          description: A nested AudienceConditionsArray
          example:
          - - and
            - audience_id: 456
            - audience_id: 789
      type: array
    AudienceConditions:
      description: An Audience Combination composed of other audiences. Each audience is a rule like 'User likes salads', and an Audience Combination is a Boolean combination of these rules, like 'User likes pizza NOT (User likes salads AND User likes soup)'.
      oneOf:
      - $ref: '#/components/schemas/AudienceConditionsArray'
      - $ref: '#/components/schemas/AudienceConditionsString'
    Metric:
      properties:
        aggregator:
          description: The aggregation function for the numerator of the metric. 'unique' measures the number of unique visitors/sessions that include the specified Event. 'count' measures the total number of occurrences of Event for the scope (visitor/session). 'sum' is the sum of the 'field' value
          enum:
          - unique
          - count
          - sum
          - ratio
          type: string
        display_title:
          description: An optional title for the unique metric configuration. If not provided, the event name will be used.
          type: string
        display_unit:
          description: An optional name for the unit of the unique metric configuration.
          type: string
        event_id:
          description: The ID for the Event to select data from. Omitted for global metrics that are not relative to a specific Event, i.e. "overall revenue"
          example: 32334454244
          format: int64
          type: integer
        event_properties:
          properties:
            filter:
              properties:
                combine_operator:
                  enum:
                  - or
                  - and
                  type: string
                conditions:
                  items:
                    $ref: '#/components/schemas/EventPropertyCondition'
              type: object
          type: object
        event_type:
          type: string
        field:
          description: The field to aggregate for the numerator of the metric. Required when 'aggregator' = 'sum', otherwise omitted
          enum:
          - revenue
          - value
          type:
          - string
          - 'null'
        id:
          description: A unique identifier for the metric configuration.
          type: string
        metrics:
          items:
            $ref: '#/components/schemas/SubMetric'
            type: object
          type: array
        project_id:
          description: A unique identifier for the project associated with the metric.
          type: integer
        scope:
          description: Specifies how Events should be grouped together. Can also be thought of as the denonimator of the metric. 'session' divides by the number of sessions. "Influenced sessions", or sessions that do not contain a decision Event but carry a decision from a previous session are not included in counts for numerator or denominator. 'visitor' divides by the number of visitors. 'event' divides by the total occurrences (impressions) of the specified Event
          enum:
          - session
          - visitor
          - event
          type: string
        visibility:
          description: The visibility of the metric.
          enum:
          - account
          - experiment
          - project
          type: string
        winning_direction:
          description: The winning direction of this metric
          enum:
          - increasing
          - decreasing
          type: string
      required:
      - winning_direction
      - aggregator
      type: object
    PatchRequestBody:
      description: A JSONPatch document as defined by RFC 6902
      properties:
        from:
          description: A JSON Pointer to the resource attribute
          type: string
        op:
          description: The operation to be performed
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
          type: string
        path:
          description: A JSON-Pointer to the resource or the resource attribute
          type: string
        value:
          anyOf:
          - type: object
          - items:
              type: string
            type: array
          - $ref: '#/components/schemas/AudienceConditions'
          - type: string
          - type: integer
          - type: boolean
          - items:
              $ref: '#/components/schemas/SubMetric'
            type: array
          description: The value to be used within the operations.
      required:
      - op
      - path
      type: object
    UrlValue:
      description: A single url.
      type: string
    RuleMap:
      additionalProperties:
        $ref: '#/components/schemas/RulesetRule'
      example:
        landing_page_callout:
          archived: false
          audience_conditions:
          - or
          - audience_id: 5340810295
          audience_ids:
          - 5340810295
          created_time: '2021-02-03 19:57:31.357168+00:00'
          description: null
          distribution_mode: stats_accelerator
          enabled: true
          fetch_results_ui_url: '...'
          id: 1
          key: landing_page_callout
          metrics:
          - aggregator: sum
            display_title: Increasing Revenue by Session
            event_id: 33333333
            event_type: custom
            field: revenue
            scope: session
            winning_direction: increasing
          name: Landing Page Callout
          percentage_included: 5000
          type: a/b
          updated_time: '2021-02-03 20:14:21.494855+00:00'
          urn: rules.flags.optimizely.com::1
          variations:
            'false':
              key: false
              name: false
              percentage_included: 5000
            'true':
              key: true
              name: true
              percentage_included: 5000
        paid_users:
          archived: false
          audience_conditions:
          - or
          - audience_id: 123456
          audience_ids:
          - 123456
          created_time: '2021-02-03 19:57:31.366368+00:00'
          description: null
          enabled: true
          id: 2
          key: paid_users
          metrics: []
          name: Paid Users
          percentage_included: 10000
          type: targeted_delivery
          updated_time: '2021-02-03 20:14:21.530632+00:00'
          urn: rules.flags.optimizely.com::2
          variations:
            'true':
              key: true
              name: true
              percentage_included: 10000
      type: object
    Ruleset_2:
      description: Rules configuration specific to an environment.
      properties:
        archived:
          description: Whether this Ruleset is archived or not. The ruleset is archived if the Flag was archived.
          example: false
          readOnly: true
          type: boolean
        default_variation_key:
          description: User-facing Unique identifier of the Variation.
          example: high_discount
          type: string
        default_variation_name:
          description: User friendly identifer of the Variation.
          example: High Discount
          readOnly: true
          type: string
        disable_url:
          example: '...'
          oneOf:
          - $ref: '#/components/schemas/UrlValue'
          readOnly: true
        enable_url:
          example: '...'
          oneOf:
          - $ref: '#/components/schemas/UrlValue'
          readOnly: true
        enabled:
          default: false
          description: Indicates if the rule is enabled or not in an environment.
          type: boolean
        environment_id:
          description: Environment id.
          type: number
        environment_key:
          description: User-facing Environment identifier.
          example: production
          type: string
        environment_name:
          description: Environment name.
          example: Production
          type: string
        fetch_default_variation_url:
          description: A url to the variation that will be executed if no rule audience is served.
          readOnly: true
          type: string
        fetch_flag_url:
          description: A url to fetch the Flag used by this Ruleset.
          oneOf:
          - $ref: '#/components/schemas/UrlValue'
          readOnly: true
        flag_key:
          description: User-facing Unique identifier of the Flag.
          example: recurring_deposit
          type: string
        id:
          example: 23456746
          readOnly: true
          type: integer
        revision:
          description: Revision number for tracking changes
          readOnly: true
          type: integer
        role:
          description: Granular permission role
          example: admin
          readOnly: true
          type: string
        rule_priorities:
          description: Ordered array of rule keys for the set.
          example:
          - new_users
          - paid_users
          - trial_users
          items:
            type: string
          type: array
        rules:
          allOf:
          - $ref: '#/components/schemas/RuleMap'
        status:
          description: status of ruleset.
          enum:
          - draft
          - running
          - paused
          type: string
        update_url:
          example: '...'
          oneOf:
          - $ref: '#/components/schemas/UrlValue'
          readOnly: true
        updated_time:
          description: Timestamp when the Ruleset was last updated
          example: '2019-05-08T00:00:00.000Z'
          format: date-time
          readOnly: true
          type: string
        url:
          description: Link to self
          example: '...'
          oneOf:
          - $ref: '#/components/schemas/UrlValue'
          readOnly: true
        urn:
          description: The URN for the Ruleset
          example: ruleset.flag.optimizely.com::a308d9ae-89ba-11ea-bc55-0242ac130003
          readOnly: true
          type: string
      required:
      - flag_key
      - environment_key
      - rule_priorities
      - urn
      - url
      type: object
    RulesetRuleVariation:
      example:
        key: high_discount
        name: High Discount
        percentage_included: 10000
      properties:
        id:
          description: Id of the RuleVariation
          readOnly: true
          type: integer
        key:
          description: User-facing Unique identifier of the Variation
          type: string
        name:
          description: User-facing name of the Variation
          type: string
        percentage_included:
          default: 0
          description: The percentage of the designated audiences that should get this variation, measured in basis points. 100 basis points = 1% traffic
          maximum: 10000
          minimum: 0
          type: integer
        revision:
          description: Revision number for tracking changes
          readOnly: true
          type: integer
      required:
      - key
      type: object
    RulesetRule:
      description: Configuration which contains audiences, metrics and variations.
      properties:
        allow_list:
          additionalProperties:
            $ref: '#/components/schemas/RuleAllowList'
          description: User and Variation to force in the experiment
          type: object
        archived:
          default: false
          description: Indicates if the rule is archived or not.
          type: boolean
        audience_conditions:
          description: The audiences that should see this rule. To target everyone, use the string "everyone" or omit this field. Multiple audiences can be combined with "and" or "or" using the same structure as audience conditions.
          externalDocs:
            description: same structure as audience conditions
            url: https://developers.optimizely.com/x/rest/guides/conditions/
          items:
            example:
            - or
            - audience_id: 5340810295
          type: array
        baseline_variation_id:
          description: The id of the baseline variation, the original version of an experiment(e.g. control group) against which variations are compared.
          type: integer
        comment:
          description: comment on conclusion of rule.
          type: string
        created_time:
          description: Timestamp when the Rule is created
          example: '2019-05-08T00:00:00.000Z'
          format: date-time
          readOnly: true
          type: string
        deployed_td_rule_audience_conditions:
          description: The audiences that should see this deployed Targeted delivery rule.
          items:
            example:
            - or
            - audience_id: 5340810295
          type: array
        deployed_td_rule_key:
          description: deployed_td_rule_key on conclusion of rule.
          type: string
        deployed_td_rule_percentage_included:
          default: 0
          description: The percentage of the designated audiences that should get the new targeted delevery rule, measured in basis points. 100 basis points = 1% traffic
          maximum: 10000
          minimum: 0
          type: integer
        deployed_variation_key:
          description: deployed_variation_key on conclusion of rule.
          type: string
        description:
          description: Additional context of the Rule
          example: This rule is used for delivery an experience to paid users
          type: string
        distribution_mode:
          description: Type of rule distribution.
          enum:
          - manual
          - stats_accelerator
          type: string
        enabled:
          default: true
          description: Indicates if the rule is enabled or not in an environment.
          type: boolean
        fetch_results_ui_url:
          allOf:
          - $ref: '#/components/schemas/UrlValue'
          description: A url to be used to find a particular Results page.
          readOnly: true
        group_remaining_traffic_allocation:
          description: Total remaining traffic allocation of the mutual exclusion group that this rule is in.
          readOnly: true
          type: integer
        group_rule:
          $ref: '#/components/schemas/RuleGroupRule'
        id:
          example: 45633994
          readOnly: true
          type: integer
        key:
          example: paid_users
          type: string
        layer_experiment_id:
          description: Experiment ID or Layer Experiment of a rule.
          readOnly: true
          type: integer
        layer_id:
          description: Layer ID or Campaign ID of a rule.
          readOnly: true
          type: integer
        metrics:
          description: List of metrics that are evaluated for the decision rules.
          items:
            $ref: '#/components/schemas/Metric'
          type: array
        name:
          example: Paid Users
          type: string
        outcome:
          description: outcome of rule.
          enum:
          - positive
          - negative
          - inconclusive
          type: string
        percentage_included:
          default: 0
          description: The percentage of the designated audiences that should get the decision rule, measured in basis points. 100 basis points = 1% traffic
          maximum: 10000
          minimum: 0
          type: integer
        report_key:
          description: Key identifying a particular Report.
          example: paying_users
          readOnly: true
          type: string
        revision:
          description: Revision number for tracking changes
          readOnly: true
          type: integer
        status:
          description: status of rule.
          enum:
          - draft
          - running
          - paused
          - concluded
          type: string
        type:
          description: Type of rule.
          enum:
          - targeted_delivery
          - a/b
          - multi_armed_bandit
          type: string
        updated_time:
          description: Timestamp when the Rule is updated
          example: '2019-05-08T00:00:00.000Z'
          format: date-time
          readOnly: true
          type: string
        urn:
          description: The URN for the Rule
          example: rules.flags.optimizely.com::45633910
          readOnly: true
          type: string
        variations:
          additionalProperties:
            $ref: '#/components/schemas/RulesetRuleVariation'
          description: Map of variations by variation key.
          type: object
      required:
      - key
      - name
      - type
      type: object
  responses:
    ForbiddenResponse:
      content:
        application/problem+json:
          example:
            detail: Permission denied
            status: 403
            title: Forbidden
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Do not have permission to perform the operation
    RulesetSuccessResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Ruleset_2'
      description: 'Successful retrieval or update of a Ruleset.


        The response includes RESTful JSON (https://restfuljson.org/) styled links. If a

        link is not present in the response, it indicates a user is not authorized to access

        the related resource.

        '
    BadRequestResponse:
      content:
        application/problem+json:
          example:
            detail: Another entity already exists with this same key
            status: 400
            title: Key example_entity already exists"
            uuid: 42c4c855-42f2-4c9a-8544-37b3dff706d2
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Malformed requests and invalid parameter names and types
    NotFoundResponse:
      description: Not found. No content
    ConflictResponse:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Conflicting resource state with requested action
    UnauthorizedResponse:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      description: Invalid credentials
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token or personal access token for authentication.
    BearerAuth:
      description: To get a personal token, see https://docs.developers.optimizely.com/web/docs/personal-token
      scheme: bearer
      type: http
    OAuth2:
      description: Write applications that authenticate with the REST API via OAuth 2.0.
      flows:
        authorizationCode:
          authorizationUrl: https://app.optimizely.com/oauth2/authorize
          scopes:
            all: Grants all access
          tokenUrl: https://app.optimizely.com/oauth2/token
      type: oauth2
    apiKey:
      scheme: bearer
      type: http
externalDocs:
  description: Optimizely Feature Experimentation API Documentation
  url: https://docs.developers.optimizely.com/feature-experimentation/reference/feature-experimentation-api-overview
x-refined-from:
- optimizely-feature-experimentation-openapi.yml
- optimizely-feature-experimentation-optimizely-feature-experimentation-api-openapi.json