: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.
Django API endpoints
Django serves the admin/management API for feature flags: CRUD operations, analytics, and organization-level operations. Runtime flag evaluation (/flags, /decide) is routed directly to the Rust service by Contour/Envoy at the Kubernetes infrastructure level -- these requests never reach Django. Django does make internal service-to-service HTTP calls to the Rust service for actions like my_flags and evaluation_reasons.
The /api/feature_flag/local_evaluation endpoint was historically served by a dedicated Django deployment (posthog-local-evaluation). All local evaluation traffic is now served by the Rust definitions fleet at /flags/definitions (see Rust service overview). The Django endpoint and deployment have been removed.
Architecture overview
┌─────────────────────────────────────────────────────────────────┐
│ Django API │
│ (routed via Contour from /api/* paths) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Project-scoped (CRUD + management) │
│ /api/projects/{id}/feature_flags/ │
│ │
│ Organization-scoped (cross-team ops) │
│ /api/organizations/{id}/feature_flags/ │
│ │
│ Legacy (derives team from user session) │
│ /api/feature_flag/ │
│ │
└─────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────────┐
│ Postgres │ │ Rust flags │
│ (CRUD) │ │ service │
│ │ │ (internal │
│ │ │ proxy) │
└──────────┘ └──────────────┘
Viewsets
All in posthog/api/feature_flag.py unless noted otherwise.
| Viewset | Route | Notes |
|---|---|---|
FeatureFlagViewSet |
api/projects/{id}/feature_flags/ |
Primary viewset. Full CRUD, soft delete via ForbidDestroyModel. |
LegacyFeatureFlagViewSet |
api/feature_flag/ |
Inherits FeatureFlagViewSet, derives team from session. |
OrganizationFeatureFlagView |
api/organizations/{id}/feature_flags/ |
Cross-team operations. File: posthog/api/organization_feature_flag.py. |
FlagValueViewSet |
api/projects/{id}/flag_value/ |
Returns possible values for a flag. File: posthog/api/flag_value.py. |
Endpoint reference
CRUD operations
Standard REST on /api/projects/{id}/feature_flags/. Hard DELETE is blocked — use PATCH with deleted: true for soft delete.
The v1 write API rejects an incoming filters.version key with HTTP 400 and code
reserved_config_version, regardless of FEATURE_FLAG_FILTERS_ENFORCED_RULES.
Omit that key when creating or updating targeting. The top-level version field
still provides optimistic concurrency control.
Stored filters with an absent version or numeric 1 use the existing v1 path.
Updates reject other stored formats with unsupported_config_version, including writes that omit filters or send {}.
Writes also reject dependencies on flags whose stored format is not v1 with unsupported_dependency_config_version.
This check does not migrate existing configurations.
Ordinary POST, PUT, and PATCH writes route through the feature flag facade. The serializer remains the v1 validation, approval, and persistence adapter. See API write ownership for the call path and transaction boundary.
Custom actions
| Method | URL | Description |
|---|---|---|
GET |
.../feature_flags/my_flags/ |
All flags with values for the current user (proxied to Rust service) |
GET |
.../feature_flags/evaluation_reasons/ |
Evaluate flags for a distinct_id with match reasons (proxied to Rust service) |
POST |
.../feature_flags/user_blast_radius/ |
Estimate how many users a condition affects |
POST |
.../feature_flags/{pk}/create_static_cohort_for_flag/ |
Create a static cohort from matched users |
GET |
.../feature_flags/{pk}/status/ |
Flag status (ACTIVE, STALE, DELETED, UNKNOWN) |
GET |
.../feature_flags/{pk}/dependent_flags/ |
Flags that depend on this flag |
POST |
.../feature_flags/{pk}/enable/ |
Set active: true only |
POST |
.../feature_flags/{pk}/disable/ |
Set active: false only |
POST |
.../feature_flags/{pk}/archive/ |
Set archived: true, disabling the flag in the same write when needed |
POST |
.../feature_flags/{pk}/unarchive/ |
Set archived: false only, leaving the flag disabled |
Organization endpoints
| Method | URL | Description |
|---|---|---|
GET |
/api/organizations/{id}/feature_flags/{key}/ |
Get a flag by key across all accessible teams |
POST |
/api/organizations/{id}/feature_flags/copy_flags/ |
Copy a flag from one project to target projects |
copy_flags requires editor access to feature_flag in each target project, not just visibility.
A caller who can see a project but can't edit flags there gets a failed entry for that target instead of a copy.
target_project_ids is capped at MAX_COPY_FLAGS_TARGET_PROJECTS (50) per call, and the endpoint has its own burst/sustained throttles since each target project can create cohorts and a flag.
Key actions in detail
my_flags and evaluation_reasons
Both actions proxy to the Rust flags service via get_flags_from_service() in posthog/api/services/flags_service.py. The Rust service URL defaults to http://localhost:3001 (configured via FEATURE_FLAGS_SERVICE_URL in posthog/settings/data_stores.py).
Lifecycle state actions
enable, disable, archive and unarchive are the typed alternative to PATCH for the two state fields.
None of them reads targeting from the request body, so a caller cannot send back targeting it read a moment ago.
Without version, that shrinks the lost-update window but does not close it: the serializer saves the instance get_object() loaded and Django writes every column, so an edit committed between that read and the save is still reverted.
A version-sending PATCH has the same hole, because the conflict check only fires when the caller's own fields overlap.
What these endpoints remove is the caller-held read, which spans as long as the caller takes rather than the inside of one request.
Each one delegates to the matching function in products/feature_flags/backend/facade/api.py, which routes the write through FeatureFlagSerializer — the same path PATCH uses, so the approval gate, the dependency guards, cache invalidation and activity logging all still apply.
The write bumps version under a row lock.
When enable or disable gets version, a stale value returns 409, and a config version 2 flag requires it.
archive and unarchive take no body, so the stale-write check does not run for them.
All four declare feature_flag:write, so object-level access control requires editor.
They are POST but they update, so each one hands the facade a FlagLifecycleWriteRequest that reports the write as a PATCH.
Two things branch on the method: the serializer runs create-only validation on POST, and the approval gate returns no resource id for POST, which made pending change requests for different flags collide.
A flag already in the requested state is returned unchanged with no write at all, which keeps the actions safe to retry: no version bump and no activity entry for a change that did not happen.
archive matches the UI contract by disabling an enabled flag in the same write, because an archived flag must be disabled.
unarchive leaves the flag disabled; enabling it is a separate call.
It is the one action that cannot return a 409: every gated action declines a change that sets none of active, filters and bucketing_identifier, so an archived-only write never opens a change request.
create_static_cohort_for_flag
Creates a static cohort containing all users that match a flag's conditions. This is the only remaining use of the legacy Python flag matching code in posthog/models/feature_flag/flag_matching.py.
Django model
FeatureFlag (posthog/models/feature_flag/feature_flag.py)
Key things to know:
keyis unique per team (UniqueConstraint(fields=["team", "key"]))- Hard deletes are blocked —
deletedis a soft delete flag versionfield provides optimistic concurrency control. Updates useselect_for_update()and return HTTP 409 on version mismatch.filters(JSONField) holds conditions, variants, payloads, and aggregation configensure_experience_continuityenables hash key overrides for consistent bucketing across identity changesevaluation_runtimecontrols whether a flag is evaluated client-side, server-side, or both- The
@approval_gatedecorator on updates can require approval before changes take effect
Cache invalidation: The feature_flag_changed_flags_cache (flags_cache.py) and feature_flag_changed (local_evaluation.py) signal handlers fire on save/delete, scheduling cache rebuilds via transaction.on_commit().
Related models (same file)
| Model | Purpose |
|---|---|
FeatureFlagHashKeyOverride |
Experience continuity hash key storage (managed = False, handled by Rust migrations) |
FeatureFlagDashboards |
Through table for flag <-> dashboard M2M |
FeatureFlagEvaluationTag |
Links flags to evaluation context tags |
Supporting modules
| File | Purpose |
|---|---|
posthog/models/feature_flag/flag_matching.py |
Legacy Python evaluation engine (only used for static cohort creation) |
products/feature_flags/backend/flags_cache.py |
HyperCache for the Rust flags service with signal-based invalidation |
products/feature_flags/backend/local_evaluation.py |
Prepares flag data for SDK local evaluation with HyperCache |
products/feature_flags/backend/user_blast_radius.py |
Estimates user/group match counts for conditions |
products/feature_flags/backend/blast_radius_flag_deps.py |
Sizes flag-dependency filters for that estimate as per-person match probabilities |
posthog/api/services/flags_service.py |
HTTP proxy to the Rust flags service |
Remote config endpoints
Remote config (/array/{token}/config, /array/{token}/config.js, /array/{token}/array.js) and the surveys config endpoint (/api/surveys) are no longer served by Django. They are served by the Rust hypercache service, which reads from the same RemoteConfig model populated by Django via post-save signals. See HyperCache system.
See also
- Rust service overview - Runtime flag evaluation service
- Flag evaluation engine - How flags are matched and evaluated
- HyperCache system - Multi-tier caching for flag definitions
- Experience continuity - Hash key overrides design
- Billing - Quota enforcement for feature flag requests