Segments

Segments are reusable groups of users defined by conditions. Instead of repeating the same targeting conditions across multiple flags, define a segment once and reference it in flag targeting rules.

Creating a segment

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta_users",
    "conditions": [
      { "property": "email", "operator": "contains", "value": "@beta.com" }
    ]
  }' \
  "https://edgeflags.net/api/v1/segments"

Segment keys must match the pattern [a-z0-9][a-z0-9._-]{0,127}.

Required fields

Field	Type	Description
`key`	string	Unique identifier
`conditions`	array	Array of conditions (AND logic — all must match)

Condition format

Each condition has three fields:

Field	Type	Description
`property`	string	Context property to evaluate (e.g., `email`, `plan`, or a custom attribute)
`operator`	string	Comparison operator (see Targeting Operators)
`value`	any	Value to compare against

Examples

Premium users segment

{
  "key": "premium_users",
  "conditions": [
    { "property": "plan", "operator": "in", "value": ["premium", "enterprise"] }
  ]
}

Power users segment

{
  "key": "power_users",
  "conditions": [
    { "property": "login_count", "operator": "gt", "value": 100 }
  ]
}

Internal users segment

Multiple conditions use AND logic — all must match:

{
  "key": "internal_users",
  "conditions": [
    { "property": "email", "operator": "ends_with", "value": "@yourcompany.com" },
    { "property": "role", "operator": "equals", "value": "employee" }
  ]
}

Using segments in flag targeting

Reference segments in flag targeting rules using the segment property with in or not_in operators:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new_dashboard",
    "enabled": true,
    "targeting": {
      "rules": [
        {
          "conditions": [
            { "property": "segment", "operator": "in", "value": ["beta_users", "premium_users"] }
          ],
          "value": true
        }
      ]
    }
  }' \
  "https://edgeflags.net/api/v1/flags"

This flag returns true for users in either the beta_users or premium_users segment.

Segment membership is evaluated lazily — segments are only loaded from KV when a targeting rule references them. Results are cached per request to avoid redundant lookups.

Excluding segments

Use not_in to exclude users in specific segments:

{
  "conditions": [
    { "property": "segment", "operator": "not_in", "value": ["blocked_users"] }
  ],
  "value": true
}

Updating a segment

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "property": "email", "operator": "contains", "value": "@beta.com" },
      { "property": "plan", "operator": "not_equals", "value": "free" }
    ]
  }' \
  "https://edgeflags.net/api/v1/segments/beta_users"

Supports optimistic concurrency with If-Match.

Deleting a segment

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/segments/beta_users"

Listing segments

curl -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/segments?limit=50&offset=0"