Optimizely Flags API

openapi: 3.2.0
info:
  title: Optimizely Flags API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Flags 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: Flags
  description: Create and manage feature flags with variables and variations for controlled rollouts and experimentation.
paths:
  /projects/{project_id}/flags:
    get:
      operationId: listFlags
      summary: List flags
      description: Returns a list of feature flags for the specified project.
      tags:
      - Flags
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Successfully retrieved the list of flags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flag'
        '401':
          description: Authentication credentials are missing or invalid
      security:
      - bearerAuth: []
    post:
      operationId: createFlag
      summary: Create a flag
      description: Creates a new feature flag within the specified project with the given key, variables, and variations.
      tags:
      - Flags
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagInput'
      responses:
        '201':
          description: Flag successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flag'
        '400':
          description: Invalid request body
        '401':
          description: Authentication credentials are missing or invalid
      security:
      - bearerAuth: []
    patch:
      description: 'Update one or more Flags in a project using a json patch structure.


        Properties that are readOnly that are present in the request body will be ignored as well as

        unknown properties.

        '
      operationId: update_flags
      parameters:
      - $ref: '#/components/parameters/projectId_2'
      requestBody:
        content:
          application/json-patch+json:
            example:
            - op: replace
              path: /recurring_deposit/description
              value: Updated description for recurring deposit flag
            schema:
              items:
                $ref: '#/components/schemas/PatchRequestBody'
              type: array
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                recurring_deposit:
                  account_id: 12345
                  archive_url: '...'
                  archived: false
                  created_time: '2019-05-08T00:00:00.000Z'
                  delete_url: string
                  description: Updated description for recurring deposit flag
                  environments:
                    development:
                      disable_url: '...'
                      enable_url: '...'
                      enabled: false
                      is_primary: false
                      key: development
                      name: Development
                      priority: 2
                      rules_detail:
                      - audience_ids:
                        - 1
                        created_time: '2022-01-08T00:00:00.000Z'
                        days_running: 30
                        enabled: true
                        id: 123
                        key: a/b
                        name: A/B Test
                        primary_metric: conversion_rate
                        traffic_allocation: 100
                        type: experiment
                        updated_time: '2022-01-08T00:00:00.000Z'
                      rules_summary:
                        a/b:
                          keys:
                          - new_users
                        targeted_delivery:
                          keys:
                          - paid_users
                          - trial_users
                    production:
                      disable_url: '...'
                      enable_url: '...'
                      enabled: false
                      key: production
                      name: Production
                      priority: 1
                      rules_detail:
                      - audience_ids:
                        - 1
                        created_time: '2022-01-08T00:00:00.000Z'
                        days_running: 30
                        distribution_mode: manual
                        enabled: true
                        fetch_results_ui_url: '...'
                        id: 123
                        key: a/b
                        layer_experiment_id: 345
                        name: A/B Test
                        primary_metric: conversion_rate
                        traffic_allocation: 100
                        type: experiment
                        updated_time: '2022-01-08T00:00:00.000Z'
                      rules_summary:
                        a/b:
                          keys:
                          - new_users
                        targeted_delivery:
                          keys:
                          - paid_users
                          - trial_users
                  id: 45633994
                  key: recurring_deposit
                  name: Recurring Deposit
                  outlier_filtering_enabled: false
                  project_id: 12345
                  unarchive_url: '...'
                  update_url: '...'
                  updated_time: '2019-05-08T00:00:00.000Z'
                  url: '...'
                  urn: flags.flag.optimizely.com::asdfsdf-2344-efadf03-343434-efrrr
                  variable_definitions:
                    advanced:
                      default_value: "{\n\t\"hello\": 123\n}"
                      description: This variable is used to configure the advanced used for advanced purposes
                      key: advanced
                      type: json
                    amount:
                      default_value: '0.0'
                      description: This variable is used to configure the amount used for computing the discount
                      key: amount
                      type: double
                    message:
                      default_value: Use recurring deposits to compound interest
                      description: This variable is used to configure the message used for displaying the discount
                      key: message
                      type: string
                  owner_user_id: 1234-abcd-5678-efgh
                  team_ids:
                  - '1234567890'
                  - 0987654321
              schema:
                $ref: '#/components/schemas/FlagMap'
          description: 'Successful update, archive or unarchive of Flags.


            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.

            '
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
      summary: Update Flags
      tags:
      - Flags
      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}:
    get:
      operationId: getFlag
      summary: Get a flag
      description: Retrieves the details of a specific feature flag by its key.
      tags:
      - Flags
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      responses:
        '200':
          description: Successfully retrieved the flag
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flag'
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag not found
      security:
      - bearerAuth: []
    patch:
      operationId: updateFlag
      summary: Update a flag
      description: Updates the specified feature flag with the provided fields.
      tags:
      - Flags
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagInput'
      responses:
        '200':
          description: Flag successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flag'
        '400':
          description: Invalid request body
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag not found
      security:
      - bearerAuth: []
    delete:
      operationId: deleteFlag
      summary: Delete a flag
      description: Permanently deletes the specified feature flag.
      tags:
      - Flags
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/flagKey'
      responses:
        '204':
          description: Flag successfully deleted
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Flag 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/archived:
    post:
      description: 'Archive one or more Flags in a project.


        This operation corresponds to the `archive_url` in a Flags response.

        '
      operationId: archive_flags
      parameters:
      - $ref: '#/components/parameters/projectId_2'
      requestBody:
        content:
          application/json:
            example:
              keys:
              - recurring_deposit
            schema:
              $ref: '#/components/schemas/BulkOperationsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                recurring_deposit:
                  account_id: 12345
                  archive_url: '...'
                  archived: true
                  created_time: '2019-05-08T00:00:00.000Z'
                  delete_url: string
                  description: Flag used for driving customers to use recurring deposits by showing a graph of compound interest over time
                  environments:
                    development:
                      disable_url: '...'
                      enable_url: '...'
                      enabled: false
                      is_primary: false
                      key: development
                      name: Development
                      priority: 2
                      rules_detail:
                      - audience_ids:
                        - 1
                        created_time: '2022-01-08T00:00:00.000Z'
                        days_running: 30
                        enabled: true
                        id: 123
                        key: a/b
                        name: A/B Test
                        primary_metric: conversion_rate
                        traffic_allocation: 100
                        type: experiment
                        updated_time: '2022-01-08T00:00:00.000Z'
                      rules_summary:
                        a/b:
                          keys:
                          - new_users
                        targeted_delivery:
                          keys:
                          - paid_users
                          - trial_users
                    production:
                      disable_url: '...'
                      enable_url: '...'
                      enabled: false
                      key: production
                      name: Production
                      priority: 1
                      rules_detail:
                      - audience_ids:
                        - 1
                        created_time: '2022-01-08T00:00:00.000Z'
                        days_running: 30
                        enabled: true
                        id: 123
                        key: a/b
                        name: A/B Test
                        primary_metric: conversion_rate
                        traffic_allocation: 100
                        type: experiment
                        updated_time: '2022-01-08T00:00:00.000Z'
                      rules_summary:
                        a/b:
                          keys:
                          - new_users
                        targeted_delivery:
                          keys:
                          - paid_users
                          - trial_users
                  id: 45633994
                  key: recurring_deposit
                  name: Recurring Deposit
                  outlier_filtering_enabled: false
                  project_id: 12345
                  unarchive_url: '...'
                  update_url: '...'
                  updated_time: '2019-05-08T00:00:00.000Z'
                  url: '...'
                  urn: flags.flag.optimizely.com::asdfsdf-2344-efadf03-343434-efrrr
                  variable_definitions:
                    advanced:
                      default_value: "{\n\t\"hello\": 123\n}"
                      description: This variable is used to configure the advanced used for advanced purposes
                      key: advanced
                      type: json
                    amount:
                      default_value: '0.0'
                      description: This variable is used to configure the amount used for computing the discount
                      key: amount
                      type: double
                    message:
                      default_value: Use recurring deposits to compound interest
                      description: This variable is used to configure the message used for displaying the discount
                      key: message
                      type: string
                  owner_user_id: 1234-abcd-5678-efgh
                  team_ids:
                  - '1234567890'
                  - 0987654321
              schema:
                $ref: '#/components/schemas/FlagMap'
          description: 'Successful archive of Flags.


            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.

            '
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
      summary: Archive Flags
      tags:
      - Flags
      security:
      - apiKey: []
      - OAuth2:
        - read
        - write
    servers:
    - url: https://api.optimizely.com/flags/v1/
  /projects/{project_id}/flags/unarchived:
    post:
      description: 'Unarchive one or more Flags in a project.


        This operation corresponds to the `unarchive_url` in a Flags response.

        '
      operationId: unarchive_flags
      parameters:
      - $ref: '#/components/parameters/projectId_2'
      requestBody:
        content:
          application/json:
            example:
              keys:
              - recurring_deposit
            schema:
              $ref: '#/components/schemas/BulkOperationsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                recurring_deposit:
                  account_id: 12345
                  archive_url: '...'
                  archived: false
                  created_time: '2019-05-08T00:00:00.000Z'
                  delete_url: string
                  description: Flag used for driving customers to use recurring deposits by showing a graph of compound interest over time
                  environments:
                    development:
                      disable_url: '...'
                      enable_url: '...'
                      enabled: false
                      is_primary: false
                      key: development
                      name: Development
                      priority: 2
                      rules_summary:
                      - audience_ids:
                        - 1
                        created_time: '2022-01-08T00:00:00.000Z'
                        days_running: 30
                        enabled: true
                        key: a/b
                        name: A/B Test
                        primary_metric: conversion_rate
                        traffic_allocation: 100
                        type: experiment
                        updated_time: '2022-01-08T00:00:00.000Z'
                    production:
                      disable_url: '...'
                      enable_url: '...'
                      enabled: false
                      key: production
                      name: Production
                      priority: 1
                      rules_detail:
                      - audience_ids:
                        - 1
                        created_time: '2022-01-08T00:00:00.000Z'
                        days_running: 30
                        enabled: true
                        id: 123
                        key: a/b
                        name: A/B Test
                        primary_metric: conversion_rate
                        traffic_allocation: 100
                        type: experiment
                        updated_time: '2022-01-08T00:00:00.000Z'
                      rules_summary:
                        a/b:
                          keys:
                          - new_users
                        targeted_delivery:
                          keys:
                          - paid_users
                          - trial_users
                  id: 45633994
                  key: recurring_deposit
                  name: Recurring Deposit
                  outlier_filtering_enabled: false
                  project_id: 12345
                  unarchive_url: '...'
                  update_url: '...'
                  updated_time: '2019-05-08T00:00:00.000Z'
                  url: '...'
                  urn: flags.flag.optimizely.com::asdfsdf-2344-efadf03-343434-efrrr
                  variable_definitions:
                    advanced:
                      default_value: "{\n\t\"hello\": 123\n}"
                      description: This variable is used to configure the advanced used for advanced purposes
                      key: advanced
                      type: json
                    amount:
                      default_value: '0.0'
                      description: This variable is used to configure the amount used for computing the discount
                      key: amount
                      type: double
                    message:
                      default_value: Use recurring deposits to compound interest
                      description: This variable is used to configure the message used for displaying the discount
                      key: message
                      type: string
                  owner_user_id: 1234-abcd-5678-efgh
                  team_ids:
                  - '1234567890'
                  - 0987654321
              schema:
                $ref: '#/components/schemas/FlagMap'
          description: 'Successful unarchive of Flags.


            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.

            '
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
      summary: Unarchive Flags
      tags:
      - Flags
      security:
      - apiKey: []
      - OAuth2:
        - read
        - write
    servers:
    - url: https://api.optimizely.com/flags/v1/
components:
  parameters:
    projectId:
      name: project_id
      in: path
      required: true
      description: The unique identifier for the project
      schema:
        type: integer
        format: int64
    flagKey:
      name: flag_key
      in: path
      required: true
      description: The unique key for the feature flag
      schema:
        type: string
    flagKey_2:
      description: The Flag identifier
      example: recurring_deposit
      in: path
      name: flag_key
      required: true
      schema:
        type: string
    pageWindow:
      description: Number of previous and next page links to supply for the request (defaults to 1).
      in: query
      name: page_window
      schema:
        type: integer
    projectId_2:
      description: The project identifier
      example: 12345
      in: path
      name: project_id
      required: true
      schema:
        type: integer
    pageToken:
      description: Pagination page token. Implements prev, next, last, first
      in: query
      name: page_token
      schema:
        type: string
    pageNumber:
      description: Bypass page_token to jump to specific page
      in: query
      name: page_number
      schema:
        format: int64
        type: integer
    perPage:
      description: The max number of items to include per page or results.
      in: query
      name: per_page
      schema:
        format: int64
        type: integer
  schemas:
    FlagVariationInput:
      type: object
      description: Input for creating or updating a flag variation
      properties:
        key:
          type: string
          description: Unique key for the variation
        name:
          type: string
          description: Human-readable name of the variation
        variables:
          type: object
          description: Map of variable keys to their values
          additionalProperties:
            type: string
    FlagEnvironment:
      type: object
      description: Flag configuration for a specific environment
      properties:
        enabled:
          type: boolean
          description: Whether the flag is enabled in this environment
        ruleset:
          $ref: '#/components/schemas/Ruleset'
    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'
    Variable:
      type: object
      description: A variable within a feature flag
      properties:
        key:
          type: string
          description: Unique key for the variable
        type:
          type: string
          description: Data type of the variable
          enum:
          - string
          - integer
          - double
          - boolean
          - json
        default_value:
          type: string
          description: Default value of the variable
    Flag:
      type: object
      description: A feature flag with variables and variations
      properties:
        key:
          type: string
          description: Unique key for the flag
        name:
          type: string
          description: Human-readable name of the flag
        description:
          type: string
          description: Description of the flag purpose
        project_id:
          type: integer
          format: int64
          description: The project this flag belongs to
        variables:
          type: array
          description: List of variables associated with this flag
          items:
            $ref: '#/components/schemas/Variable'
        variations:
          type: array
          description: List of variations for this flag
          items:
            $ref: '#/components/schemas/FlagVariation'
        environments:
          type: object
          description: Map of environment keys to flag environment configurations
          additionalProperties:
            $ref: '#/components/schemas/FlagEnvironment'
        created:
          type: string
          format: date-time
          description: Timestamp when the flag was created
        last_modified:
          type: string
          format: date-time
          description: Timestamp when the flag was last modified
    FlagVariation:
      type: object
      description: A variation of a feature flag with variable values
      properties:
        key:
          type: string
          description: Unique key for the variation
        name:
          type: string
          description: Human-readable name of the variation
        variables:
          type: object
          description: Map of variable keys to their values for this variation
          additionalProperties:
            type: string
    FlagInput:
      type: object
      description: Input for creating or updating a flag
      properties:
        key:
          type: string
          description: Unique key for the flag
        name:
          type: string
          description: Human-readable name of the flag
        description:
          type: string
          description: Description of the flag purpose
        variables:
          type: array
          description: List of variables associated with this flag
          items:
            $ref: '#/components/schemas/VariableInput'
        variations:
          type: array
          description: List of variations for this flag
          items:
            $ref: '#/components/schemas/FlagVariationInput'
    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
    VariableInput:
      type: object
      description: Input for creating or updating a variable
      properties:
        key:
          type: string
          description: Unique key for the variable
        type:
          type: string
          description: Data type of the variable
          enum:
          - string
          - integer
          - double
          - boolean
          - json
        default_value:
          type: string
          description: Default value of the variable
    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
    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
    VariableDefinition:
      properties:
        default_value:
          description: The default value for the Flag Variable Definition
          example: '0.0'
          type: string
        description:
          description: Additional context of the Flag Variable Definition
          example: This variable is used to configure the amount used for computing the discount
          type: string
        key:
          description: Unique string identifier for the Flag Variable Definition within the Flag
          example: amount
          type: string
        revision:
          description: Revision number for tracking changes
          readOnly: true
          type: integer
        role:
          description: Granular permission role
          example: admin
          readOnly: true
          type: string
        type:
          description: The datatype for the Flag Variable Definition
          enum:
          - boolean
          - string
          - double
          - integer
          - json
          example: double
          type: string
      required:
      - key
      - type
      - default_value
      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
    SubMetric:
      properties:
        aggregator:
          type: string
        event_id:
          type: integer
        event_ty

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/optimizely/refs/heads/main/openapi/optimizely-flags-api-openapi.yml