Django API endpoints

Django serves the admin/management API for feature flags: CRUD operations, local SDK evaluation, 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 (used by server-side SDKs for local flag evaluation) runs on a dedicated Django deployment (posthog-local-evaluation), separate from the main Django web service.

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.

Endpoint reference

CRUD operations

Standard REST on /api/projects/{id}/feature_flags/. Hard DELETE is blocked — use PATCH with deleted: true for soft delete.

Custom actions

Organization endpoints

Key actions in detail

local_evaluation

Returns flag definitions for SDKs that evaluate flags locally (server-side SDKs). Response includes flags (via MinimalFeatureFlagSerializer), group_type_mapping, and optionally cohort definitions. Supports ETag-based caching. Uses HyperCache with Redis -> S3 -> PostgreSQL fallback.

Requires ProjectSecretAPIKeyAuthentication. Rate limited at 600/minute (overridable per team via LOCAL_EVAL_RATE_LIMITS). Checks billing quotas via list_limited_team_attributes.

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).

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:

• key is unique per team (UniqueConstraint(fields=["team", "key"]))
• Hard deletes are blocked — deleted is a soft delete flag
• version field provides optimistic concurrency control. Updates use select_for_update() and return HTTP 409 on version mismatch.
• filters (JSONField) holds conditions, variants, payloads, and aggregation config
• ensure_experience_continuity enables hash key overrides for consistent bucketing across identity changes
• evaluation_runtime controls whether a flag is evaluated client-side, server-side, or both
• The @approval_gate decorator on updates can require approval before changes take effect

Cache invalidation: The refresh_flag_cache_on_updates signal handler fires on save/delete, calling set_feature_flags_for_team_in_cache() via transaction.on_commit().

Related models (same file)

Supporting modules

Remote config endpoints

Separate from the feature flag viewset, remote config is served by unauthenticated public views. The token in the URL is a public identifier, not a credential.

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