:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Feature flag API writes
Ordinary feature flag POST, PUT, and PATCH requests enter facade.api.create_flag or facade.api.update_flag through FeatureFlagViewSet.create and FeatureFlagViewSet.update.
The viewset retains authentication, API scopes, project scoping, object permissions, approval exception handling, and response serialization.
It passes the original request and serializer context to the facade, including PUT versus partial-update semantics.
The facade uses FeatureFlagSerializer as the existing v1 write adapter.
Each write validates and saves once.
The serializer owns request validation, approvals, persistence, tags, evaluation contexts, audit history, analytics, and cache side effects.
The facade's serializer dependency is legacy; this path does not establish a pattern for new facade contracts or product isolation.
Stored configurations with an absent filters.version or a numeric value equal to 1 use v1 validation.
Other stored formats fail with unsupported_config_version before v1 normalization, including updates that omit filters or supply {}; stored version 2 rows take the separate path described under "Config version 2 writes".
Every incoming filters.version, including numeric 1, still fails with reserved_config_version, except a version 2 document sent to a project the writer policy admits.
Supplied top-level v1 filter keys replace those keys in the stored state; {} retains targeting and groups: [] clears it.
The existing validation rollout controls normalization and unknown-key preservation.
Every write rejects the variant keys $false and $true with reserved_variant_key, whatever the validation rollout enforces.
It also rejects a "null" or empty "" variant key unless the stored flag already has a variant with that key.
flag_evaluations stores a "null" response the same as a null one, and a "" response the same as a missing one.
The validation rollout's structural.multivariate.variants[].key.blank rule rejects every "" key, including one the stored flag has, once that rule is enforced.
Copies follow the target flag, not the source.
Duplicating an experiment with a new flag key, copying a flag or experiment to a project without that flag, and copying onto a target flag that lacks the source flag's "null" or "" variant all fail.
Dependency targets must also use v1 configurations.
The dependency validator resolves IDs within the existing project scope, rejects disabled targets, and checks filters.version before accepting an edge.
During the cycle walk, reference resolution checks each target's format before reading its v1 properties, including reachable targets without groups.
A rejected format returns unsupported_dependency_config_version at filters, identifying the target by ID without including its configuration.
The check adds no database queries to the existing person-condition dependency walk.
Group-only conditions and writes that re-enable a flag or restore an active deleted flag also check reachable target formats, independently of structural-validation rollout settings. This supplementary traversal fetches pending targets in batches of at most 100 IDs and visits each ID once, without scanning the whole project. This check does not enable group dependencies: their existing aggregation validation still applies. Metadata-only and empty-filter updates retain their existing no-op targeting semantics unless they make stored targeting usable again. Restoring a deleted flag that stays disabled does not require repairing its dependencies. Disabling, archival, and deletion retain their existing dependent-flag protections.
| Source configuration | Target configuration | Write behavior |
|---|---|---|
| V1 | Absent version, numeric 1, or numeric 1.0 | Existing dependency validation |
| V1 | Numeric 2 or 2.0 | Reject the dependency |
| V1 | Null, string, boolean, or another version | Reject the dependency |
| V2 | Any flag dependency | Rejected by the strict v2 validator |
The row's FeatureFlag.version remains an independent concurrency counter.
Conversion attempts remain blocked by incoming-version rejection and the stored-format write guard.
A future converter must reject conversion of a target with inbound v1 dependencies before changing its configuration format.
Do not wrap facade writes in an outer transaction. An approval-required write creates a pending change request and then raises; an outer transaction would roll that request back. The serializer's existing update transaction locks the flag and increments its row version. Its other effects retain their existing placement outside that transaction.
Service callers retain their request shims, actor attribution, and system-write behavior. Facade updates reload stored encrypted payloads before returning a model for reuse. Both HTTP write adapters apply the existing authentication-dependent payload renderer: personal API keys receive plaintext and other authentication receives a redacted placeholder. Empty-filter updates preserve the stored ciphertext without encrypting it again.
A rollback restores ordinary HTTP routing to the previous serializer path. Keep any format rejection or reader capability required by configuration data that exists at rollback time. In particular, retain v1-to-v2 dependency protection once v2 targets can exist; rollback does not convert stored configurations to v1.
Config version 2 writes
Two internal feature flags form the writer policy, evaluated by facade.config_writes for the project group (targeted by project id) with local evaluation only, so an unresolved flag reads as off:
feature-flag-rules-v2-writes: the projects whose flags may be created, updated and enabled with config version 2.feature-flag-rules-v2-creation: whether an admitted project may create a new version 2 flag. Turning it off leaves existing rows updatable, enableable and disableable.
Nothing else grants admission: no request field, serializer context flag, staff status, internal team or missing user.
FEATURE_FLAG_RULES_V2_MAX_METADATA_BYTES bounds one rule's opaque metadata object in an admitted write; the default is pilot scope and is revisited before users author documents through the editor or broader API use.
The deployment filter-size limit (MAX_FEATURE_FLAG_FILTER_SIZE_BYTES) bounds the whole document, as it does for v1.
| Operation | Requires | Closed |
|---|---|---|
Create (POST with filters.version 2) |
Admitted project, creation enabled, no active: true |
Every other project keeps reserved_config_version; active: true is rejected rather than downgraded |
Full-document update (filters) |
Admitted project, current version |
|
Metadata update (name, key, tags) |
Admitted project, current version |
Every other field, including archived, remote config and payload fields |
Enable (active: true) |
Admitted project, current version, stored document valid under current limits |
|
Disable (active: false) |
Current version only |
An enabled flag-write approval policy, like every other row here |
Delete (deleted: true, the soft delete) |
Current version only; disables an enabled row in the same write |
Restore (deleted: false); the separate archived field and the /archive/ action; an enabled policy |
A stored version 2 row that is not remote-configured and carries no encrypted payloads always takes this path, whatever its project: disabling and soft-deleting are the pilot's incident controls and do not depend on either writer flag.
- A new row is created disabled with server-owned rule IDs and seeds; the request document is resolved against an empty stored document and validated strictly before it is persisted exactly. No v1 row is converted.
- A supplied
filtersobject replaces the whole configuration. There is no top-level merge, no rule merge by index, no filling of omitted fields from the stored document, and no v1 normalization.{},null, a list, and an incomplete object are invalid; a complete document withrules: []is valid. return_typeisboolean,string,numberorobjectand cannot change after creation.default_valueis null or the declared type; every rulevalueand variantvalueis the declared type. Strings are non-empty and not$false,$trueor"null", the values v1 also reserves as variant keys; numbers lie within ±(2^53 − 1); objects nest at most 20 object or array levels with numbers in the same range.- Writer-only rules (
check_writer_rulesinfacade/config_writes.py, currently the$false,$trueand"null"reservation and the regex check below) apply to a created or replacing document and to the stored document being enabled. The shared validator, and with it the flags caches and the stored side of an update, does not apply them: tightening a writer rule never hides a stored row from evaluation or blocks replacing it. A"null"value the stored document already serves, as the default, a rule value or a variant value, passes the reservation, as in v1. - Experiment-rule variant keys follow the v1 variant-key rule for every return type: a new
"null"key is rejected, writer-only, unless the stored rule with the same ID already uses that key. The key belongs to that rule's experiment, so another rule cannot take it over. regexandnot_regexpatterns must compile with Python'sre, as on the v1 write path. This is a writer-only rule: readers store an uncompilable pattern and report an evaluation error when evaluation reaches it. The flags service compiles withfancy_regex, whose dialect differs at the edges, so, as in v1, a pattern the stored document already holds is not checked again, and enabling checks no pattern.- Rule types are
targeted_release,percentage_rolloutandexperiment. An experiment rule names no Experiment: an Experiment links to its rule through the rule ID (Experiment.feature_flag_rule_id), and writing the rule creates or links no Experiment row. The rule splits the subjects itsrollout_percentageenrolls across two to twentyvariants(unique keys of letters, digits,-and_; weights with at most two decimal places that total exactly 100; values of the flag's return type, equal values allowed), returns the flag default whilepausedis true, and may carry aholdoutthat belongs to the rule:{seed, exclusion_percentage}, where the client choosesexclusion_percentageand the server owns the seed. At/flags?v=4a variant assignment reportsexperiment_splitwith the rule ID and the variant key; no response carries an experiment or holdout ID. Anexperiment_idon the rule and anidin its holdout are unknown fields, whatever their value,nullincluded. - Rule IDs, the seeds of percentage rollouts and experiment rules, and holdout seeds are server-owned and identify rules rather than list positions. An echoed ID keeps its seeds through reordering and unrelated edits, and a rule keeps its seed while it stays a percentage rollout or an experiment rule; a rule that omits its ID is new and receives fresh identity. An unknown ID, an ID used twice, a client-chosen seed, and a changed seed are all rejected.
FeatureFlag.versionis required on every update and must equal the locked row's value. Unlike v1 there is nooriginal_flagmerge: a stale token is a conflict even when no individual field clashes. The token applies to disabling and deleting too.- Identity resolution, validation and the enable check run against the locked row inside the existing update transaction. A stored document with an unsupported shape or semantics is rejected rather than replaced or enabled. Configuration and metadata byte limits apply to a replacement, so an oversized stored document can be edited back under a lowered limit; enabling requires the stored document to fit the current limits.
- Request bytes that repeat a JSON key are rejected before normalization can hide the duplicate. Non-finite numbers and percentages with more than two decimal places are rejected by the validator itself.
- A rejected document returns the validator's first error: its path in
attr, with nested keys joined by__as for nested serializer errors (for examplefilters__rules__0__valueforfilters.rules[0].value, orfiltersfor the whole document), the bare message indetail, and itscode(the handler rendersinvalidasinvalid_input). An unknown field returnsattr: filterswith its path indetail, because the path ends in the client's key name and could read as another field's path. A repeated JSON key returnsattr: null, because the key can be anywhere in the request body. - An enabled flag-write approval policy (
feature_flag.enable,feature_flag.disableorfeature_flag.update, on the team or its organization) denies every version 2 write, disable and delete included, and an approved change cannot be applied to a version 2 row: PH-WRITE-APPROVAL owns that path. Nothing here creates a pending change request; to disable a version 2 flag under such a policy, disable the policy first. The final policy lookup and flag mutation share an organization-scoped transaction lock with policy creation and updates, so a policy cannot be enabled between that lookup and commit. Flag writes take the lock in shared mode so different flags can update concurrently; policy writes take it in exclusive mode. - Each accepted write saves once, increments
versiononce, runs the existing cache invalidation and produces one activity log entry through the existing receiver. The entry carries the generic field diff; canonical version 2 summaries and version-history reconstruction are later work.
Rollback turns both flags off. Existing version 2 rows stay readable, disableable and deletable; there is no data conversion, and v1-to-v2 dependency protection is not removed.
A flags service that predates experiment rules fails a flag that has one, in the same way as below. Deploy the flags service that evaluates them before an admitted project writes one, and disable every such enabled flag before reverting that service.
A flags service that predates string, number and object values fails such a flag: the flag gets an error entry and the whole /flags response sets errorsWhileComputingFlags, so posthog-js merges it into its cached flags instead of replacing them. Deploy the flags service that evaluates these types before an admitted project creates one. Turning the writer flags off stops new ones but leaves enabled ones served; disable every enabled string, number and object flag before reverting the flags service.