The decide
endpoint is used to evaluate a feature flag for a given user. This means it is the main endpoint not only for feature flags, but also experimentation, early access features, and survey display conditions.
It is a POST-only public endpoint that uses your project API key and does not return any sensitive data from your PostHog instance.
Note: Make sure to send API requests to the correct domain. These are
https://us.i.posthog.com
for US Cloud,https://eu.i.posthog.com
for EU Cloud, and your self-hosted domain for self-hosted instances. Confirm yours by checking your URL from your PostHog instance.
There are 3 steps to implement feature flags using the PostHog API:
Step 1: Evaluate the feature flag value using decide
decide
is the endpoint used to determine if a given flag is enabled for a certain user or not.
Request
curl -v -L --header "Content-Type: application/json" -d ' {"api_key": "<ph_project_api_key>","distinct_id": "distinct_id_of_your_user","groups" : {"group_type": "group_id"}}' https://us.i.posthog.com/decide?v=3
Note: The
groups
key is only required for group-based feature flags. If you use it, replacegroup_type
andgroup_id
with the values for your group such ascompany: "Twitter"
.
Response
When called, decide
returns the flag values and payloads, along with more information.
{"config": {"enable_collect_everything": true},"toolbarParams": {},"errorComputingFlags": false,"isAuthenticated": false,"supportedCompression": ["gzip","lz64"],"featureFlags": {"my-awesome-flag": true,"my-awesome-flag-2": true,"my-multivariate-flag": "some-string-value","flag-thats-not-on": false,},"featureFlagPayloads": {"my-awesome-flag": "example-payload-string","my-awesome-flag-2": "{\"color\": \"blue\", \"animal\": \"hedgehog\"}"}}
Note:
errorComputingFlags
will returntrue
if we didn't manage to compute some flags (for example, if there's an ongoing incident involving flag evaluation).This enables partial updates to currently active flags in your clients.
Step 2: Include feature flag information when capturing events
If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API.
To do this, include the $feature/feature_flag_name
property in your event:
curl -v -L --header "Content-Type: application/json" -d ' {"api_key": "<ph_project_api_key>","event": "your_event_name","distinct_id": "distinct_id_of_your_user","properties": {"$feature/feature-flag-key": "variant-key" # Replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant}}' https://us.i.posthog.com/capture/
Step 3: Send a $feature_flag_called
event
To track usage of your feature flag and view related analytics in PostHog, submit the $feature_flag_called
event whenever you check a feature flag value in your code.
You need to include two properties with this event:
$feature_flag_response
: This is the name of the variant the user has been assigned to e.g., "control" or "test"$feature_flag
: This is the key of the feature flag in your experiment.
curl -v -L --header "Content-Type: application/json" -d ' {"api_key": "<ph_project_api_key>","event": "$feature_flag_called","distinct_id": "distinct_id_of_your_user","properties": {"$feature_flag": "feature-flag-key","$feature_flag_response": "variant-name"}}' https://us.i.posthog.com/capture/
Advanced: Overriding server properties
Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties
, groups
, and group properties
arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
curl -v -L --header "Content-Type: application/json" -d ' {"api_key": "<ph_project_api_key>","distinct_id": "distinct_id_of_your_user","groups" : { # Required only for group-based feature flags"group_type": "group_id" # Replace "group_type" with the name of your group type. Replace "group_id" with the id of your group.},"person_properties": {"<personProp1>": "<personVal1>"}, # Optional. Include any properties used to calculate the value of the feature flag."group_properties": {"group type": {"<groupProp1>":"<groupVal1>"}} # Optional. Include any properties used to calculate the value of the feature flag.}' https://us.i.posthog.com/decide?v=3
Overriding GeoIP properties
By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
To override the GeoIP properties used to evaluate a feature flag, provide an IP address in the HTTP_X_FORWARDED_FOR
when making your /decide
request:
curl -v -L \--header "Content-Type: application/json" \--header "HTTP_X_FORWARDED_FOR: the_client_ip_address_to_use " \-d ' {"api_key": "<ph_project_api_key>","distinct_id": "distinct_id_of_your_user"}' https://us.i.posthog.com/decide?v=3
The list of properties that this overrides:
$geoip_city_name
$geoip_country_name
$geoip_country_code
$geoip_continent_name
$geoip_continent_code
$geoip_postal_code
$geoip_time_zone