Feature flags

Last updated:

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

PostHog provides you with an API endpoint to create and update your feature flags. This section refers to that endpoint specifically.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint for checking if feature flags are enabled for a given user.

Endpoints

GETPOST
/api/feature_flag
GETPUTPATCHDELETE
/api/feature_flag/<flag_id:int>

Examples

Create Feature flags

POST /feature_flag/

Data

AttributeTypeRequiredDefaultDescription
nameStringYesThe name you wish to give to your feature flag. Helps identify the flag easily when using the PostHog UI.
keyStringYesThe actual identifier of your flag to be used when referencing it in your app's logic.
activeBooleanNoFalseToggles the flag on and off.
rollout_percentageIntegerNoNonePercentage of users with the specified filters that ther given flag will apply to. If filters are not specified, this will be a percentage of your total users.
filtersHash TableNo{}Properties of users to be matched for a flag to be on.
personal_api_keyStringYesYour Personal API Key from the Project Settings page.

Example request

curl -i -X POST \
-F 'active=true' \
-F 'filter={properties: [{key: "signed_up", value: "true", type: "person"}]}' \
-F 'name=Feature Flag' \
-F 'key=flag' \
-F 'rollout_percentage=20' \
-F 'personal_api_key=<your_key>' \
-L -v 'https://[your-instance].com/api/feature_flag/'

Example response

{
"id": 123,
"name": "My Flag",
"key": "my-flag",
"rollout_percentage": 20,
"filters": {
"properties": [
{
"key": "signed_up",
"type": "person",
"value": "true"
}
]
},
"deleted": false,
"active": true,
"created_by": {
"id": 123,
"distinct_id": "4aa16b878667376032ced03c6f434b5932f",
"first_name": "John",
"email": "john.smith@fakeemail.com"
},
"created_at": "2020-09-02T18:36:15.993777Z"
}

Get the details of a flag

GET /feature_flag/123/

Data

To get the details of a given feature flag, pass its ID directly on the path. You can pass your Personal API Key as an HTTP header, and no additional data is required.

Example request

curl -i \
-H "Authorization: Bearer <your_key>" \
-L -v "https://[your-instance].com/api/feature_flag/123/"

Example response

{
"id": 123,
"name": "My Flag",
"key": "my-flag",
"rollout_percentage": 20,
"filters": {
"properties": [
{
"key": "signed_up",
"type": "person",
"value": "true"
}
]
},
"deleted": false,
"active": true,
"created_by": {
"id": 123,
"distinct_id": "4aa16b878667376032ced03c6f434b5932f",
"first_name": "John",
"email": "john.smith@fakeemail.com"
},
"created_at": "2020-09-02T18:36:15.993777Z"
}

Update the details of a flag

PATCH /feature_flag/123/

Data

Passing the ID of the flag directly in the path, include any values from the table shown under 'Create Feature Flags' that you wish to update. The personal_api_key is the only required field.

Example request

curl -i -X PATCH \
-F 'active=false' \
-F 'rollout_percentage=50' \
-F 'personal_api_key=<your_key>' \
-L -v 'https://[your-instance].com/api/feature_flag/123/'

Example response

{
"id": 123,
"name": "My Flag",
"key": "my-flag",
"rollout_percentage": 50,
"filters": {
"properties": [
{
"key": "signed_up",
"type": "person",
"value": "true"
}
]
},
"deleted": false,
"active": false,
"created_by": {
"id": 123,
"distinct_id": "4aa16b878667376032ced03c6f434b5932f",
"first_name": "John",
"email": "john.smith@fakeemail.com"
},
"created_at": "2020-09-02T18:36:15.993777Z"
}