From 7f3d9742a46feb0897a2dcdd67d61d73004465b7 Mon Sep 17 00:00:00 2001 From: Kwame Efah Date: Mon, 29 Sep 2025 15:54:39 -0700 Subject: [PATCH 1/3] Add API docs for feature flagging --- reference/Feature Flags API/feature-flags.md | 9 +++++++++ .../Feature Flags API/flags/get-flag-definitions.md | 10 ++++++++++ .../flags/get-variant-assignments.md | 10 ++++++++++ reference/Mixpanel APIs/overview.md | 11 +++++++++-- 4 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 reference/Feature Flags API/feature-flags.md create mode 100644 reference/Feature Flags API/flags/get-flag-definitions.md create mode 100644 reference/Feature Flags API/flags/get-variant-assignments.md diff --git a/reference/Feature Flags API/feature-flags.md b/reference/Feature Flags API/feature-flags.md new file mode 100644 index 0000000000..357681bfb0 --- /dev/null +++ b/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. diff --git a/reference/Feature Flags API/flags/get-flag-definitions.md b/reference/Feature Flags API/flags/get-flag-definitions.md new file mode 100644 index 0000000000..63b6acf48a --- /dev/null +++ b/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. diff --git a/reference/Feature Flags API/flags/get-variant-assignments.md b/reference/Feature Flags API/flags/get-variant-assignments.md new file mode 100644 index 0000000000..5d1c912295 --- /dev/null +++ b/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. diff --git a/reference/Mixpanel APIs/overview.md b/reference/Mixpanel APIs/overview.md index 1b5ca48f87..0ba3b78cc1 100644 --- a/reference/Mixpanel APIs/overview.md +++ b/reference/Mixpanel APIs/overview.md @@ -15,10 +15,10 @@ The API endpoints are organized by the function that they support. The API struc **Standard Server:** `api.mixpanel.com` **EU Residency Server:** `api-eu.mixpanel.com` **India Residency Server:** `api-in.mixpanel.com` -Use the Ingestion API to get your data into Mixpanel. This includes live events, historical imports, and user profile data. +Use the Ingestion API to get your data into Mixpanel. This includes live events, historical imports, and user profile data. > 🚧 Data Residency -> +> > To ensure data ingests into your project, use the correct Ingestion API subdomain for your project's data residency. For more information, you can learn more about: [EU Residency](https://docs.mixpanel.com/docs/privacy/eu-residency) and [IN Residency](https://docs.mixpanel.com/docs/privacy/in-residency). ### [**Query API**](ref:query-api) @@ -62,3 +62,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. From 7fb01cac7f0c6bd05af696990c028793297da23e Mon Sep 17 00:00:00 2001 From: Kwame Efah Date: Mon, 29 Sep 2025 16:36:02 -0700 Subject: [PATCH 2/3] Add api docs for feature flags --- openapi/openapi.config.yaml | 3 + openapi/src/featureflags.openapi.yaml | 323 ++++++++++++++++++++++++++ 2 files changed, 326 insertions(+) create mode 100644 openapi/src/featureflags.openapi.yaml diff --git a/openapi/openapi.config.yaml b/openapi/openapi.config.yaml index a2e3d7d45a..7d60a677a9 100644 --- a/openapi/openapi.config.yaml +++ b/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 diff --git a/openapi/src/featureflags.openapi.yaml b/openapi/src/featureflags.openapi.yaml new file mode 100644 index 0000000000..e5b1b7f08d --- /dev/null +++ b/openapi/src/featureflags.openapi.yaml @@ -0,0 +1,323 @@ +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 + 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 + 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' \ No newline at end of file From ad9e203ba82027822e2545c838a84b5294db39b3 Mon Sep 17 00:00:00 2001 From: Kwame Efah Date: Mon, 29 Sep 2025 16:45:54 -0700 Subject: [PATCH 3/3] minor updates to openapi spec --- openapi/src/featureflags.openapi.yaml | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/openapi/src/featureflags.openapi.yaml b/openapi/src/featureflags.openapi.yaml index e5b1b7f08d..6ee1183038 100644 --- a/openapi/src/featureflags.openapi.yaml +++ b/openapi/src/featureflags.openapi.yaml @@ -2,7 +2,7 @@ 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. + 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: @@ -10,7 +10,20 @@ info: url: https://opensource.org/licenses/MIT version: 1.0.0 servers: - - $ref: ./common/app-api.yaml#/server + - 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 @@ -19,7 +32,7 @@ tags: paths: /flags: get: - operationId: get-variant-assignments + operationId: get-variant-assignments parameters: - name: context in: query @@ -30,7 +43,7 @@ paths: example: '%7B%22distinct_id%22%3A%22user123%22%2C%22device_id%22%3A%22device456%22%7D' tags: - Evaluate Flags - summary: Evaluate Feature Flags (GET) + 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':