API specs for flags endpoints

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,331 @@
+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 properties for cohort evaluation
+          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_definition:
+          type: object
+          additionalProperties: true
+          description: Properties that are evaluated at request time for cohort matching
+          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:
+          $ref: '#/components/schemas/VariantOverride'
+    VariantOverride:
+      title: VariantOverride
+      description: Override to force a specific variant for a rollout rule
+      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,13 @@
+---
+title: Get Flag Definitions
+category:
+  uri: 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.

reference/Feature Flags API/flags/get-variant-assignments.md

@@ -0,0 +1,13 @@
+---
+title: Get Variant Assignments
+category:
+  uri: Feature Flags API
+content:
+  excerpt: >-
+    This endpoint returns the variant assignments for enabled flags within a
+    Mixpanel project
+privacy:
+  view: public
+---
+
+This endpoint returns a map from all feature flags that are provisioned within a Mixpanel project to the variant that the current user context is assigned to.

reference/Mixpanel APIs/overview.md

@@ -63,3 +63,10 @@ The retrieval and deletion API calls are updated for version 3 and are made for
 **EU Residency Server:** `eu.mixpanel.com/api/app/projects`
 **India Residency Server:** `in.mixpanel.com/api/app/projects`
 Use the Warehouse Connectors API to manually run a warehouse imports.
+
+### [**Feature Flags API**](ref:feature-flags-api)
+
+**Standard Server:** `api.mixpanel.com/flags`
+**EU Residency Server:** `api-eu.mixpanel.com/flags`
+**India Residency Server:** `api-in.mixpanel.com/flags`
+Use the Feature Flags API to assign your users to variants for experiments, rollout, and releases.