Evaluate flags

The POST/flags endpoint allows you to send a context object serialized as JSON and retrieve all active flags at once for that context.

Evaluating a single context

The context object is a JSON object that can contain any key/value pairs you want.

JSON
cURL
{
  "userId": "foo",
  "email": "foo@gmail.com"
}

The response is a JSON object listing all active flags and their corresponding values for that context:

{
  "flagA": null,
  "flagC": "foo",
  "flagD": false
}
Warning

Since the value of a flag can be falsy, you must check if a key exists to determine if a flag is active or not. Checking the value may lead to false negatives.

Interpreting the response

Most of the time, checking if a key exists is enough, but if you want to do anything more complex than on / off, you might need to read the flag's value.

The above response can be interpreted as follows:

  • flagA is active, and its value is null.
  • flagB is inactive, deleted, or maybe it just does not exist. (It is simply not part of the response)
  • flagC is active, and its value is "foo"
  • flagD is active, and its value is false
Tip

It might be tempting to think that values of null or false means that the flag is inactive, but it is not. Inactive flags are just not in the response, there might be a few reasons for that:

  • The flag does not exist, it was never created
  • The flag exists but is archived
  • The flag exists but it is inactive (the main switch is off on the app)
  • The flag exists, it is active, but for that particular context the conditions make it fall into the inactive variation

Evaluating flags in batches

On the backend you might need to evaluate a lot of contexts at once. Doing multiple HTTP requests will kill performance, you can instead pass an array of contexts in a single API call and get back an array of responses.

JSON
cURL
[
  { "userId": "foo" },
  { "userId": null },
  { "userId": "baz" }
]

Contexts objects do not have to share the same keys. The response is an array of the same length:

[
    {
      "flagA": null,
      "flagC": "foo",
      "flagD": false
    },
    {
      "flagC": "foo"
    },
    {
      "flagA": null,
      "flagD": true
    }
]

You can interpret the response the same way as before.

PreviousAPI reference
NextGet flags config