Feature flags API Reference

Feature flags

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`GET`
`POST`
`POST`
`POST`
`POST`
`GET`
`GET`
`GET`
`POST`
`GET`
`GET`
`GET`
`POST`

List all feature flags

This endpoint returns a list of feature flags and their details like name, key, variants, rollout_percentage, and more.

To evaluate and determine the value of flags for a given user, use the flags endpoint instead.

Required API key scopes

feature_flag:read

Path parameters

project_id
string

Query parameters

active
string
One of: "STALE""false""true"
created_by_id
string
evaluation_runtime
string
One of: "both""client""server"
excluded_properties
string
has_evaluation_tags
string
One of: "false""true"
limit
integer
offset
integer
search
string
tags
string
type
string
One of: "boolean""experiment""multivariant"

Response

Example request

GET /api/projects/:project_id/feature_flags

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/

Example response

Status 200

RESPONSE

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "deleted": true,
      "active": true,
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {
          "property1": null,
          "property2": null
        },
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0,
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {
          "property1": null,
          "property2": null
        },
        "role_at_organization": "engineering"
      },
      "is_simple_flag": true,
      "rollout_percentage": 0,
      "ensure_experience_continuity": true,
      "experiment_set": "string",
      "surveys": {
        "property1": null,
        "property2": null
      },
      "features": {
        "property1": null,
        "property2": null
      },
      "rollback_conditions": null,
      "performed_rollback": true,
      "can_edit": true,
      "tags": [
        null
      ],
      "evaluation_tags": [
        null
      ],
      "usage_dashboard": 0,
      "analytics_dashboards": [
        0
      ],
      "has_enriched_analytics": true,
      "user_access_level": "string",
      "creation_context": "feature_flags",
      "is_remote_configuration": true,
      "has_encrypted_payloads": true,
      "status": "string",
      "evaluation_runtime": "server",
      "bucketing_identifier": "distinct_id",
      "last_called_at": "2019-08-24T14:15:22Z",
      "_create_in_folder": "string",
      "_should_create_usage_dashboard": true
    }
  ]
}

Create feature flags

Required API key scopes

feature_flag:write

Path parameters

project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Response

Example request

POST /api/projects/:project_id/feature_flags

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/\
	-d key="string"

Example response

Status 201

RESPONSE

{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {
    "property1": null,
    "property2": null
  },
  "deleted": true,
  "active": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0,
  "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "is_simple_flag": true,
  "rollout_percentage": 0,
  "ensure_experience_continuity": true,
  "experiment_set": "string",
  "surveys": {
    "property1": null,
    "property2": null
  },
  "features": {
    "property1": null,
    "property2": null
  },
  "rollback_conditions": null,
  "performed_rollback": true,
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_tags": [
    null
  ],
  "usage_dashboard": 0,
  "analytics_dashboards": [
    0
  ],
  "has_enriched_analytics": true,
  "user_access_level": "string",
  "creation_context": "feature_flags",
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "status": "string",
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "_create_in_folder": "string",
  "_should_create_usage_dashboard": true
}

Retrieve feature flags

This endpoint returns a feature flag and its details like name, key, variants, rollout_percentage, and more.

To evaluate and determine the value of a flag for a given user, use the flags endpoint instead.

Required API key scopes

feature_flag:read

Path parameters

id
integer
project_id
string

Response

Example request

GET /api/projects/:project_id/feature_flags/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/

Example response

Status 200

RESPONSE

{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {
    "property1": null,
    "property2": null
  },
  "deleted": true,
  "active": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0,
  "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "is_simple_flag": true,
  "rollout_percentage": 0,
  "ensure_experience_continuity": true,
  "experiment_set": "string",
  "surveys": {
    "property1": null,
    "property2": null
  },
  "features": {
    "property1": null,
    "property2": null
  },
  "rollback_conditions": null,
  "performed_rollback": true,
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_tags": [
    null
  ],
  "usage_dashboard": 0,
  "analytics_dashboards": [
    0
  ],
  "has_enriched_analytics": true,
  "user_access_level": "string",
  "creation_context": "feature_flags",
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "status": "string",
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "_create_in_folder": "string",
  "_should_create_usage_dashboard": true
}

Update feature flags

Required API key scopes

feature_flag:write

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Response

Example request

PATCH /api/projects/:project_id/feature_flags/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/\
	-d name="string"

Example response

Status 200

RESPONSE

{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {
    "property1": null,
    "property2": null
  },
  "deleted": true,
  "active": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0,
  "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "is_simple_flag": true,
  "rollout_percentage": 0,
  "ensure_experience_continuity": true,
  "experiment_set": "string",
  "surveys": {
    "property1": null,
    "property2": null
  },
  "features": {
    "property1": null,
    "property2": null
  },
  "rollback_conditions": null,
  "performed_rollback": true,
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_tags": [
    null
  ],
  "usage_dashboard": 0,
  "analytics_dashboards": [
    0
  ],
  "has_enriched_analytics": true,
  "user_access_level": "string",
  "creation_context": "feature_flags",
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "status": "string",
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "_create_in_folder": "string",
  "_should_create_usage_dashboard": true
}

Delete feature flags

Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true

Required API key scopes

feature_flag:write

Path parameters

id
integer
project_id
string

Example request

DELETE /api/projects/:project_id/feature_flags/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/

Example response

Status 405 No response body

Retrieve feature flags activity retrieve

Required API key scopes

activity_log:read

Path parameters

id
integer
project_id
string

Example request

GET /api/projects/:project_id/feature_flags/:id/activity

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/activity/

Example response

Status 200 No response body

Create feature flags create static cohort for flag

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/create_static_cohort_for_flag

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/create_static_cohort_for_flag/\
	-d key="string"

Example response

Status 200 No response body

Create feature flags dashboard

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/dashboard

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/dashboard/\
	-d key="string"

Example response

Status 200 No response body

Create feature flags enrich usage dashboard

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/enrich_usage_dashboard

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/enrich_usage_dashboard/\
	-d key="string"

Example response

Status 200 No response body

Create feature flags has active dependents

Check if this flag has other active flags that depend on it.

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/has_active_dependents

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/has_active_dependents/\
	-d key="string"

Example response

Status 200 No response body

Retrieve feature flags remote config

Required API key scopes

feature_flag:read

Path parameters

id
integer
project_id
string

Example request

GET /api/projects/:project_id/feature_flags/:id/remote_config

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/remote_config/

Example response

Status 200 No response body

Retrieve feature flags status

Required API key scopes

feature_flag:read

Path parameters

id
integer
project_id
string

Example request

GET /api/projects/:project_id/feature_flags/:id/status

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/status/

Example response

Status 200 No response body

Retrieve feature flags activity

Required API key scopes

activity_log:read

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/activity

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/activity/

Example response

Status 200 No response body

Create feature flags bulk keys

Get feature flag keys by IDs. Accepts a list of feature flag IDs and returns a mapping of ID to key.

Path parameters

project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/bulk_keys

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/bulk_keys/\
	-d key="string"

Example response

Status 200 No response body

Retrieve feature flags evaluation reasons

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/evaluation_reasons

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/evaluation_reasons/

Example response

Status 200 No response body

Retrieve feature flags local evaluation

Required API key scopes

feature_flag:read

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/local_evaluation

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/local_evaluation/

Example response

Status 200 No response body

Retrieve feature flags my flags

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/my_flags

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/my_flags/

Example response

Status 200 No response body

Create feature flags user blast radius

Path parameters

project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/user_blast_radius

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/user_blast_radius/\
	-d key="string"