openapi spec for flags endpoints

openapi/openapi.config.yaml

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

openapi/src/featureflags.openapi.yaml

@@ -0,0 +1,336 @@
+openapi: 3.0.2
+info:
+  title: Feature Flags API
+  description: >-
+    Use the Feature Flags API to assign users to feature flag variants and to 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:
+  - url: https://{region}.mixpanel.com
+    description: Mixpanel's data collection server.
+    variables:
+      region:
+        default: api
+        enum:
+          - api
+          - api-eu
+          - api-in
+        description: >
+          The server location to be used:
+            * `api` - The default (US) servers used for most projects
+            * `api-eu` - EU servers if you are enrolled in EU Data Residency
+            * `api-in` - India servers if you are enrolled in India Data Residency
+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
+      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: Gets variant assignment
+      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
+      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:
+  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'
+        request_time_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_definition:
+          type: object
+          additionalProperties: true
+          description: Definition of the cohort this rollout applies to
+          example:
+            country: 'US'
+            user_type: 'premium'
+        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_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/feature-flags.md

@@ -0,0 +1,9 @@
+---
+title: "Overview"
+slug: "feature-flags-api"
+hidden: false
+createdAt: "2025-09-29T19:07:58.032Z"
+updatedAt: "2025-09-29T19:14:28.849Z"
+---
+
+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/get-flag-definitions.md

@@ -0,0 +1,10 @@
+---
+title: "Get Flag Definitions"
+slug: "get-flag-definitions"
+excerpt: "This endpoint returns the flag definitions for all enabled feature flags within a Mixpanel project."
+hidden: false
+createdAt: "2025-09-29T19:07:58.032Z"
+updatedAt: "2025-09-29T19:14:28.849Z"
+---
+
+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,10 @@
+---
+title: "Get Variant Assignments"
+slug: "get-variant-assignments"
+excerpt: "This endpoint returns the variant assignments for enabled flags within a Mixpanel project"
+hidden: false
+createdAt: "2025-09-29T19:07:58.032Z"
+updatedAt: "2025-09-29T19:14:28.849Z"
+---
+
+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.