feat(__future__): Experimental update-flag

[emyller]

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Contributes to #7642

Stabilises experimental update-flag endpoints to one option, still experimental.

• Avoids touching Options A + B — cleanup + interface migration PR will follow.
• Foundation of the code is in an experimental namespace.
• Includes multivariate flag support.
• Improves API design.

Updated documentation: https://docs-git-feat-update-flag-option-c-flagsmith.vercel.app/managing-flags/updating-flags

How did you test this code?

Integration tests included.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 7, 2026 3:16pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
flagsmith-frontend-preview	Ignored	Preview	Aug 7, 2026 3:16pm
flagsmith-frontend-staging	Ignored	Preview	Aug 7, 2026 3:16pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 182a6163-fa2e-43a4-afb3-ede6b6264395

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[khvn26]

Looks good overall. My main gripe is combining full-replace and delete: true semantics for lists of different entities in a single API.

[matthewelwell]

I'm not sure I agree that modifying the variants themselves should be part of this endpoint at all. variants (or MultivariateFeatureOptions) are project level concepts. This endpoint should be concerned only with environment level entities.

IMO we should raise an error if a variant key is provided that doesn't already exist.

[khvn26]

I actually thought this was implied by

The variants list in segment_overrides can only re-weight existing variants.

[matthewelwell]

That's not how I understood it - I understood that there was a difference in behaviour between the environment_default section of the payload, and the segment_overrides on this matter. TBC by @emyller .

[emyller]

My honest understanding of adding MVs support to update-flag was that it could be used to configure a multivariate experiment. If it's not, I think I need to learn more about the use case.

[emyller]

Leaning towards knowledge I'm yet to learn: e111394

[khvn26]

Current experiments UI does not allow to add, delete or modify variants — unless I'm missing something, it consumes existing ones.

[emyller]

This should be ready for a new review: since 81077d9, I've updated the proposed documentation to make it consistent to our [offline] discussion. Will update tests and move right on to implementing it once this looks good.

I've opted to let go of a separate DELETE endpoint, as it seemingly has no use in the UI, which is satisfied with a PUT path. Overall I think all the PATCH path isn't much useful to our dashboard, but it definitely helps ergonomics if we need it, e.g. in the CLI.

[khvn26]

I guess my only question at this point is whether we stick with feature_id/feature_name addressing on the API side, or only accept feature ids — this is not apparent from the docs currently.

[emyller]

I guess my only question at this point is whether we stick with feature_id/feature_name addressing on the API side, or only accept feature ids — this is not apparent from the docs currently.

I decided not to support feature names in this endpoint, for now, because we know no consumer that would benefit from it yet. The proposed docs assumes this discussion never existed, and includes {feature_id} in the example URLs. Let me know if you think anything should be improved towards that.