Create Feature Flag

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

integer

required

Project ID

Request Body

string

required

Unique identifier for the flag. Only letters, numbers, hyphens (-) and underscores (_) allowed. Max 400 characters.

string

Human-readable description of the flag (despite field name, this is the description)

boolean

default:"true"

Whether the flag is active

object

required

Release conditions for the feature flag

array

required

Array of condition groups. At least one group required.

number

Percentage of users to roll out to (0-100)

array

Property filters for this group

string

required

Property name

string

required

Property type: person, group, cohort, or flag

any

required

Value to match against

string

Comparison operator: exact, is_not, icontains, regex, gt, gte, lt, lte, is_set, is_not_set, is_date_before, is_date_after, etc.

string

Override to serve a specific variant to this group (multivariate flags only)

object

Multivariate flag configuration

array

required

Array of variants. Rollout percentages must sum to 100.

string

required

Variant identifier

string

Variant display name

number

required

Percentage allocation for this variant (0-100)

object

JSON payloads to return with flag evaluation. Keys must match variant keys for multivariate flags, or be “true” for boolean flags.

number

Group type index for group-based flags (0-4)

boolean

default:"false"

Ensure consistent experience for anonymous users across sessions

array

Array of tag names to associate with this flag

array

Array of tag names for runtime evaluation context constraints (must be subset of tags)

array

Conditions that trigger automatic rollback

boolean

default:"false"

Whether payloads are encrypted

Response

integer

Feature flag ID

string

Feature flag key

string

Feature flag description

object

Release conditions

boolean

Whether the flag is active

boolean

Whether the flag is soft-deleted

string

ISO 8601 timestamp

object

User who created the flag

array

Associated tags

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
        }
      ]
    }
  }'

import requests

response = requests.post(
    "https://app.posthog.com/api/projects/:project_id/feature_flags",
    headers={
        "Authorization": "Bearer <ph_project_api_key>",
        "Content-Type": "application/json"
    },
    json={
        "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": "user@example.com",
    "first_name": "Jane",
    "email": "user@example.com"
  },
  "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
}

Overview

Events

Feature Flags

Cohorts

Insights

Create Feature Flag

POST /api/projects/:id/feature_flags

Path Parameters

Request Body

Response

Examples

Boolean Flag with Rollout Percentage

Flag with Property Filters

Multivariate Flag with Variants

Flag with Cohort Filter

Response Example

​POST /api/projects/:id/feature_flags

​Path Parameters

​Request Body

​Response

​Examples

​Boolean Flag with Rollout Percentage

​Flag with Property Filters

​Multivariate Flag with Variants

​Flag with Cohort Filter

​Response Example

POST /api/projects/:id/feature_flags

Path Parameters

Request Body

Response

Examples

Boolean Flag with Rollout Percentage

Flag with Property Filters

Multivariate Flag with Variants

Flag with Cohort Filter

Response Example