Decide feature flags API endpoint

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 targeting.

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"
    }
}' <ph_client_api_host>/decide?v=3

Note: The groups key is only required for group-based feature flags. If you use it, replace group_type and group_id with the values for your group such as company: "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 return true 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
    }
}' <ph_client_api_host>/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:

1. $feature_flag_response: This is the name of the variant the user has been assigned to e.g., "control" or "test"
2. $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"
    }
}' <ph_client_api_host>/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.
}' <ph_client_api_host>/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"
}' <ph_client_api_host>/decide?v=3

The list of properties that this overrides:

1. $geoip_city_name
2. $geoip_country_name
3. $geoip_country_code
4. $geoip_continent_name
5. $geoip_continent_code
6. $geoip_postal_code
7. $geoip_time_zone