FlowynBETA
LoginSign up

Flag evaluation

Evaluates a flag for an identifier and attributes you send. Rules run in order and the first match wins; percentage conditions bucket the identifier deterministically. The response carries the value and the reason.

What flag evaluation does

Evaluates a flag for an identifier and attributes you send. Rules run in order and the first match wins; percentage conditions bucket the identifier deterministically. The response carries the value and the reason.

When to use flag evaluation

  • Feature gating
  • Remote configuration for applications and agents
  • Per-plan behaviour

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/flags/evaluate

Request

The body is JSON.

curl -X POST https://api.flowyn.dev/v1/flags/evaluate \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "checkout-v2",
    "identifier": "usr_142",
    "attributes": {
      "plan": "pro",
      "country": "DE"
    }
  }'

Response

Flowyn returns HTTP 200. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "key": "checkout-v2",
  "environment": "test",
  "enabled": true,
  "value": true,
  "reason": "percentage_rollout",
  "matched_rule_id": "rule_rollout_25",
  "bucket": 1742,
  "configuration_version": 7,
  "algorithm_version": "v1"
}

Lifecycle

  1. Create the flag with a key, value_type (boolean, string, number, or json), a default_value, and optional rules.
  2. Your application sends the key, an identifier, and attributes.
  3. Rules are evaluated in order. The first rule whose conditions all match returns its value with reason: targeting_match.
  4. A percentage condition hashes the identifier into a bucket from 0 to 9,999 and matches below the configured basis points (reason: percentage_rollout).
  5. Otherwise the default is returned with reason: default.

Status values

StatusMeaning
targeting_matchA rule matched; matched_rule_id names it.
percentage_rolloutA percentage rule matched; bucket is returned.
defaultNo rule matched.
disabledThe flag is turned off in this environment.
unconfiguredThe flag has no value in this environment.
archivedThe flag is archived.

Retries

Evaluation is synchronous and read-only. Retry freely.

Idempotency

Not needed. The same configuration version, identifier, and attributes always return the same value.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • Up to 20 attributes; string values up to 256 characters
  • Up to 20 rules per flag, 8 conditions per rule
  • Values up to 10 KB

Create a flag

bash
curl -X POST https://api.flowyn.dev/v1/flags \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: flag-checkout-v2" \
  -d '{
    "key": "checkout-v2",
    "name": "Checkout v2",
    "value_type": "boolean",
    "enabled": true,
    "default_value": false
  }'

Next step

Read Percentage rollouts.