Skip to main content

​
POST /api/projects/:id/feature_flags

Creates a new feature flag in your PostHog project. Feature flags allow you to roll out features to specific users or groups based on properties, cohorts, and rollout percentages.

​
Path Parameters

​
id
integer
required
Project ID

​
Request Body

​
key
string
required
Unique identifier for the flag. Only letters, numbers, hyphens (-) and underscores (_) allowed. Max 400 characters.
​
name
string
Human-readable description of the flag (despite field name, this is the description)
​
active
boolean
default:"true"
Whether the flag is active
​
filters
object
required
Release conditions for the feature flag
​
groups
array
required
Array of condition groups. At least one group required.
​
rollout_percentage
number
Percentage of users to roll out to (0-100)
​
properties
array
Property filters for this group
​
key
string
required
Property name
​
type
string
required
Property type: person, group, cohort, or flag
​
value
any
required
Value to match against
​
operator
string
Comparison operator: exact, is_not, icontains, regex, gt, gte, lt, lte, is_set, is_not_set, is_date_before, is_date_after, etc.
​
variant
string
Override to serve a specific variant to this group (multivariate flags only)
​
multivariate
object
Multivariate flag configuration
​
variants
array
required
Array of variants. Rollout percentages must sum to 100.
​
key
string
required
Variant identifier
​
name
string
Variant display name
​
rollout_percentage
number
required
Percentage allocation for this variant (0-100)
​
payloads
object
JSON payloads to return with flag evaluation. Keys must match variant keys for multivariate flags, or be “true” for boolean flags.
​
aggregation_group_type_index
number
Group type index for group-based flags (0-4)
​
ensure_experience_continuity
boolean
default:"false"
Ensure consistent experience for anonymous users across sessions
​
tags
array
Array of tag names to associate with this flag
​
evaluation_tags
array
Array of tag names for runtime evaluation context constraints (must be subset of tags)
​
rollback_conditions
array
Conditions that trigger automatic rollback
​
has_encrypted_payloads
boolean
default:"false"
Whether payloads are encrypted

​
Response

​
id
integer
Feature flag ID
​
key
string
Feature flag key
​
name
string
Feature flag description
​
filters
object
Release conditions
​
active
boolean
Whether the flag is active
​
deleted
boolean
Whether the flag is soft-deleted
​
created_at
string
ISO 8601 timestamp
​
created_by
object
User who created the flag
​
tags
array
Associated tags
​
version
integer
Version number for optimistic locking

​
Examples

​
Boolean Flag with Rollout Percentage

curl -X POST https://app.posthog.com/api/projects/:project_id/feature_flags \
  -H "Authorization: Bearer <ph_project_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-dashboard",
    "name": "New Dashboard Design",
    "active": true,
    "filters": {
      "groups": [
        {
          "rollout_percentage": 20
        }
      ]
    }
  }'

​
Flag with Property Filters

curl -X POST https://app.posthog.com/api/projects/:project_id/feature_flags \
  -H "Authorization: Bearer <ph_project_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta-feature",
    "name": "Beta Feature Access",
    "filters": {
      "groups": [
        {
          "properties": [
            {
              "key": "email",
              "type": "person",
              "value": "@company.com",
              "operator": "icontains"
            }
          ],
          "rollout_percentage": 100
        }
      ]
    }
  }'

​
Multivariate Flag with Variants

curl -X POST https://app.posthog.com/api/projects/:project_id/feature_flags \
  -H "Authorization: Bearer <ph_project_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "checkout-flow",
    "name": "Checkout Flow Variants",
    "filters": {
      "groups": [
        {
          "rollout_percentage": 100
        }
      ],
      "multivariate": {
        "variants": [
          {
            "key": "control",
            "name": "Control",
            "rollout_percentage": 50
          },
          {
            "key": "test",
            "name": "New Flow",
            "rollout_percentage": 50
          }
        ]
      },
      "payloads": {
        "control": "{\"button_color\": \"blue\"}",
        "test": "{\"button_color\": \"green\"}"
      }
    }
  }'

​
Flag with Cohort Filter

curl -X POST https://app.posthog.com/api/projects/:project_id/feature_flags \
  -H "Authorization: Bearer <ph_project_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "premium-features",
    "name": "Premium Features",
    "filters": {
      "groups": [
        {
          "properties": [
            {
              "key": "id",
              "type": "cohort",
              "value": 123
            }
          ],
          "rollout_percentage": 100
        }
      ]
    }
  }'
Validation Rules:
  • Flag key must be unique within the project
  • At least one condition group required
  • Multivariate variant rollout percentages must sum to 100
  • Property values in lists cannot exceed 1000 items (10 in tests)
  • Cohorts with behavioral filters (events) cannot be used in feature flags
  • Maximum flag filter size is configurable per deployment

​
Response Example

{
  "id": 12345,
  "key": "new-dashboard",
  "name": "New Dashboard Design",
  "filters": {
    "groups": [
      {
        "rollout_percentage": 20,
        "properties": []
      }
    ]
  },
  "deleted": false,
  "active": true,
  "created_by": {
    "id": 1,
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "distinct_id": "[email protected]",
    "first_name": "Jane",
    "email": "[email protected]"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "ensure_experience_continuity": false,
  "rollback_conditions": null,
  "performed_rollback": false,
  "tags": [],
  "evaluation_tags": [],
  "version": 1,
  "can_edit": true,
  "usage_dashboard": null,
  "analytics_dashboards": [],
  "has_enriched_analytics": false
}

Build docs developers (and LLMs) love

Get started for freeTalk to us