🚩 Add Feature Flags API Spec

openapi/openapi.config.yaml

@@ -8,6 +8,9 @@ apis:
   export:
     root: ./src/export.openapi.yaml
     output: ./out/event-export-api.json
+  featureflags:
+    root: ./src/featureflags.openapi.yaml
+    output: ./out/featureflags-api.json
   gdpr:
     root: ./src/gdpr.openapi.yaml
     output: ./out/gdpr-api-2.json

openapi/src/featureflags.openapi.yaml

@@ -0,0 +1,340 @@
+openapi: 3.0.2
+info:
+  title: Feature Flags API
+  description: >-
+    Use the Feature Flags API to evaluate feature flags for users and retrieve feature flag definitions.
+  contact:
+    url: 'https://mixpanel.com/get-support'
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  version: 1.0.0
+servers:
+  - $ref: ./common/app-api.yaml#/server
+tags:
+  - name: Evaluate Flags
+    description: Evaluate feature flags for a specific user
+  - name: Flag Definitions
+    description: Retrieve feature flag definitions
+paths:
+  /flags:
+    get:
+      operationId: get-variant-assignments
+      security:
+        - ProjectSecret: []
+      parameters:
+        - name: context
+          in: query
+          description: 'URL-encoded JSON object containing evaluation context with distinct_id and optional device_id, request_time_properties'
+          required: true
+          schema:
+            type: string
+          example: '%7B%22distinct_id%22%3A%22user123%22%2C%22device_id%22%3A%22device456%22%7D'
+      tags:
+        - Evaluate Flags
+      summary: Evaluate Feature Flags (GET)
+      description: Evaluate all enabled feature flags for a user with the provided context. Returns selected variants for flags the user is eligible for.
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EvaluateFlagsResponse'
+        '400':
+          $ref: ./common/responses.yaml#/400BadRequest
+        '401':
+          $ref: ./common/responses.yaml#/401Unauthorized
+        '403':
+          $ref: ./common/responses.yaml#/403Forbidden
+  /flags/definitions:
+    get:
+      operationId: get-flag-definitions
+      security:
+        - ProjectSecret: []
+      tags:
+        - Flag Definitions
+      summary: Get Feature Flag Definitions
+      description: Retrieve all enabled feature flag definitions for the authenticated project. Returns complete flag metadata including rulesets, variants, and rollout configurations.
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlagDefinitionsResponse'
+        '401':
+          $ref: ./common/responses.yaml#/401Unauthorized
+        '403':
+          $ref: ./common/responses.yaml#/403Forbidden
+components:
+  securitySchemes:
+    $ref: ./common/securitySchemes.yaml
+  schemas:
+    EvaluateFlagsRequest:
+      title: EvaluateFlagsRequest
+      description: Request body for feature flag evaluation
+      type: object
+      required:
+        - context
+      properties:
+        context:
+          $ref: '#/components/schemas/EvaluationContext'
+    EvaluationContext:
+      title: EvaluationContext
+      description: Context object containing user information and properties for flag evaluation
+      type: object
+      required:
+        - distinct_id
+      properties:
+        distinct_id:
+          type: string
+          description: The distinct ID of the user to evaluate flags for
+          example: 'user123'
+        device_id:
+          type: string
+          description: Optional device ID. If not provided, distinct_id will be used
+          example: 'device456'
+        custom_properties:
+          type: object
+          description: Optional runtime parameters for evaluation by runtime_evaluation_rule in rollout definitions
+          additionalProperties: true
+          example:
+            country: 'US'
+            platform: 'web'
+    EvaluateFlagsResponse:
+      title: EvaluateFlagsResponse
+      description: Response containing evaluated feature flags for the user
+      type: object
+      required:
+        - flags
+      properties:
+        flags:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/SelectedVariant'
+          description: Map of flag keys to their selected variants
+          example:
+            new_checkout_flow:
+              variant_key: 'treatment'
+              variant_value: true
+              experiment_id: 'exp_123'
+              is_experiment_active: true
+    SelectedVariant:
+      title: SelectedVariant
+      description: The selected variant for a feature flag
+      type: object
+      required:
+        - variant_key
+        - variant_value
+      properties:
+        variant_key:
+          type: string
+          description: The key of the selected variant
+          example: 'treatment'
+        variant_value:
+          description: The value of the selected variant (can be any type)
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+            - type: object
+          example: true
+        experiment_id:
+          type: string
+          description: The ID of the associated experiment, if any
+          example: 'exp_123'
+        is_experiment_active:
+          type: boolean
+          description: Whether the associated experiment is currently active
+          example: true
+        is_qa_tester:
+          type: boolean
+          description: Whether the user was identified as a QA tester
+          example: false
+    FlagDefinitionsResponse:
+      title: FlagDefinitionsResponse
+      description: Response containing all enabled feature flag definitions
+      type: object
+      required:
+        - flags
+      properties:
+        flags:
+          type: array
+          items:
+            $ref: '#/components/schemas/ExperimentationFlagMetadata'
+          description: Array of enabled feature flag definitions
+    ExperimentationFlagMetadata:
+      title: ExperimentationFlagMetadata
+      description: Complete metadata for a feature flag
+      type: object
+      required:
+        - id
+        - name
+        - key
+        - status
+        - project_id
+        - workspace_id
+        - ruleset
+        - context
+      properties:
+        id:
+          type: string
+          description: Unique identifier for the flag
+          example: 'flag_abc123'
+        name:
+          type: string
+          description: Human-readable name of the flag
+          example: 'New Checkout Flow'
+        key:
+          type: string
+          description: Unique key used to reference the flag
+          example: 'new_checkout_flow'
+        status:
+          type: string
+          enum: ['enabled', 'disabled', 'archived']
+          description: Current status of the flag
+          example: 'enabled'
+        project_id:
+          type: integer
+          format: int32
+          description: ID of the project this flag belongs to
+          example: 12345
+        workspace_id:
+          type: integer
+          format: int64
+          description: ID of the workspace (dataview) this flag belongs to
+          example: 67890
+        ruleset:
+          $ref: '#/components/schemas/RuleSet'
+        context:
+          type: string
+          description: The context variable used for flag evaluation (e.g., distinct_id, device_id)
+          example: 'device_id'
+        experiment_id:
+          type: string
+          description: ID of the associated experiment, if any
+          example: 'exp_123'
+        is_experiment_active:
+          type: boolean
+          description: Whether the associated experiment is currently active
+          example: true
+    RuleSet:
+      title: RuleSet
+      description: Complete ruleset for a feature flag including variants and rollout configuration
+      type: object
+      required:
+        - variants
+        - rollout
+      properties:
+        variants:
+          type: array
+          items:
+            $ref: '#/components/schemas/Variant'
+          description: Array of variant definitions for this flag
+        rollout:
+          type: array
+          items:
+            $ref: '#/components/schemas/Rollout'
+          description: Array of rollout rules defining how the flag is distributed
+        test:
+          $ref: '#/components/schemas/TestUsers'
+    Variant:
+      title: Variant
+      description: A variant definition for a feature flag
+      type: object
+      required:
+        - key
+        - value
+        - is_control
+        - split
+      properties:
+        key:
+          type: string
+          description: Unique key for this variant
+          example: 'treatment'
+        value:
+          description: The value for this variant (can be any type)
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+            - type: object
+          example: true
+        is_control:
+          type: boolean
+          description: Whether this is the control variant
+          example: false
+        is_sticky:
+          type: boolean
+          description: Whether users should stick to this variant once assigned
+          example: true
+        split:
+          type: number
+          format: double
+          description: The proportion of users that should receive this variant (0.0 to 1.0)
+          example: 0.5
+    Rollout:
+      title: Rollout
+      description: A rollout rule defining how a flag is distributed to a cohort
+      type: object
+      required:
+        - rollout_percentage
+      properties:
+        rollout_percentage:
+          type: number
+          format: double
+          description: The percentage of the cohort that should receive this flag (0.0 to 1.0)
+          example: 0.8
+        cohort_hash:
+          type: string
+          description: Hash of the cohort definition for lookup
+          example: 'cohort_abc123'
+        runtime_evaluation_rule:
+          type: object
+          additionalProperties: true
+          description: JsonLogic rule that's evaluated at request time based on runtime parameters in the request
+          example:
+            platform: 'web'
+        runtime_evaluation_definition:
+          deprecated: true
+          type: object
+          additionalProperties: true
+          description: Key-value pairs that are evaluated at request time for cohort matching, replaced by the more powerful runtime_evaluation_rule
+          example:
+            platform: 'web'
+        variant_splits:
+          type: object
+          additionalProperties:
+            type: number
+            format: double
+          description: Dictionary mapping variant keys to their allocation splits within this rollout
+          example:
+            control: 0.5
+            treatment: 0.5
+        variant_override:
+          deprecated: true
+          $ref: '#/components/schemas/VariantOverride'
+    VariantOverride:
+      deprecated: true
+      title: VariantOverride
+      description: Override to force a specific variant for a rollout rule (replaced by variant_splits)
+      type: object
+      properties:
+        key:
+          type: string
+          description: The variant key to force
+          example: 'treatment'
+    TestUsers:
+      title: TestUsers
+      description: Mapping of test users to their assigned variants
+      type: object
+      properties:
+        users:
+          type: object
+          additionalProperties:
+            type: string
+          description: Map of distinct_id to variant_key for QA testing
+          example:
+            qa_user_1: 'treatment'
+            qa_user_2: 'control'

reference/Feature Flags API/_order.yaml

@@ -0,0 +1,2 @@
+- feature-flags
+- flags

reference/Feature Flags API/feature-flags.md

@@ -0,0 +1,9 @@
+---
+title: Overview
+category:
+  uri: Feature Flags API
+privacy:
+  view: public
+---
+
+Mixpanel's Feature Flagging API's provides an interface for assigning your users to variants for feature flags defined within Mixpanel projects.

reference/Feature Flags API/flags/_order.yaml

@@ -0,0 +1,2 @@
+- get-variant-assignments
+- get-flag-definitions

reference/Feature Flags API/flags/get-flag-definitions.md

@@ -0,0 +1,15 @@
+---
+title: Get Flag Definitions
+slug: "get-flag-definitions"
+category:
+  uri: Feature Flags API
+categorySlug: "feature-flags-api"
+content:
+  excerpt: >-
+    This endpoint returns the flag definitions for all enabled feature flags
+    within a Mixpanel project.
+privacy:
+  view: public
+---
+
+This endpoint returns a set of the flag definitions that are currently provisioned within a Mixpanel project and are enabled. This is used in local evaluation by Mixpanel service side SDK's such as the Python SDK. Local evaluation polls for flag definitions according to provided configuration and assignment to a variant is implemented directly by the SDK without making a network request.