Integration Guide

{ "traceId": "0198f2b1-…", "message": "Failed to create flag" }

Notes

• Treat any non-2xx response as failure and retry only idempotent reads; do not branch on message text, which is intentionally generic and may change.
• Malformed JSON is rejected before the request reaches a handler, and the error body is plain text rather than the JSON shape above. Check the Content-Type of an error response before parsing it as JSON.

# Exchange key for a token (1 hour TTL)
curl -X POST https://api.featrs.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key_id": "<uuid>", "secret": "<secret>"}'
# → { "access_token": "eyJ…", "exp": 1711929600 }

# Use it
curl https://api.featrs.com/flags -H "Authorization: Bearer eyJ…"

Notes

• Keep tokens server-side. A token grants full read/write access to the organisation. There is no browser-safe key type, so evaluation from web or mobile clients should go through your own backend.
• Scopes are not yet enforced. Scopes supplied at key creation are recorded and embedded in the token, but endpoints do not currently check them. Treat every key as granting full organisation access until enforcement ships.
• Revocation is immediate. Tokens are re-validated against the database on every request, so revoking a key invalidates its outstanding tokens instantly rather than at expiry.
• Failed exchanges return 401 with distinct messages for invalid credentials, revoked keys, and expired keys.

Notes

• Store the secret from the create response immediately; only an Argon2 hash is retained, so it cannot be retrieved again.
• last_used_at is stamped on each successful token exchange (not on every API call), so it reflects when a key last minted a token — null means the key has never been used.
• These endpoints require a token like any other, so bootstrap the first key through the dashboard.

Notes

• PUT /flag/{id} and POST /flag/{id}/dates are full replaces, not patches. Any optional field you omit is set to NULL. To change a single field, read the flag, modify it, and send the complete body back.
• Creating a.b.c auto-creates missing ancestors a and a.b as enabled flags. If an enabled parent switch is not what you want, create the parents explicitly first with the values you intend.
• Renaming a key via PUT does not rename children — hierarchy is string-based, so renaming platform to core detaches every platform.* child from its former parent. Segment assignments and experiment links survive renames, as they reference the flag UUID.
• Restrict keys to letters, digits, _ and - between dots. Other characters are currently accepted, but a key containing / cannot be evaluated through the path-based endpoint.

# 1. Simple boolean by key
curl https://api.featrs.com/flag/evaluate/checkout.new-flow \
  -H "Authorization: Bearer $TOKEN"
# → { "key": "checkout.new-flow", "enabled": true }

# 2. With user context (segment targeting)
curl -X POST https://api.featrs.com/flag/evaluate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"key": "checkout.new-flow", "context": {"country": "ZA", "plan": "enterprise"}}'
# → { "key": "checkout.new-flow", "enabled": true, "segment_match": true }

# 3. Batch (e.g. app boot)
curl -X POST https://api.featrs.com/flags/evaluate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keys": ["checkout.new-flow", "platform.dark-mode"], "context": {"country": "ZA"}}'
# → [ { "key": "…", "enabled": true }, … ]

Notes

• Percentage rollouts are not sticky. Each evaluation is an independent random roll with no bucketing by user or context, so a user under a 25% flag may see it change between requests. For a stable per-user experience, evaluate once per session and cache the result, or keep the flag at 0/100 and use segments for targeting.
• An empty or omitted context skips segment matching entirely and reports segment_match: true. Segments only gate users when at least one context attribute is sent — no context means "do not target", not "not in any segment". Always send context if you rely on segment gating.
• Evaluating a nonexistent key is not an error — it walks the hierarchy and ultimately returns enabled: false. Typos fail silently; review /flags/stats for keys you don't recognise.
• segment_match is only returned by the single-flag context endpoint. The batch endpoint applies segment gating to enabled but does not include the per-flag segment_match breakdown.
• Batch evaluation runs keys sequentially server-side and fails the whole request if any single key errors; results come back in request order. Keep batches to the keys you actually need at boot.
• Every evaluation writes an analytics row. At high evaluation rates, prefer the batch endpoint plus client-side caching over per-request evaluation.
• Circuit breakers participate in evaluation but there is currently no API to trip or reset them; they are operated by the Featrs team. If everything under one root suddenly evaluates false, a tripped breaker is a likely cause.

[ { "flag_key": "checkout.new-flow", "total": 1523, "enabled_count": 1200,
    "last_24h": 245, "last_7d": 1102 } ]

Notes

• Stats are keyed by the string that was evaluated, not by existing flags: deleted flags and mistyped keys appear here too. Sorted by total, descending.

{ "country": "ZA", "plan": ["enterprise", "scale-up"] }

Notes

• Matching is case-sensitive ("ZA" ≠ "za"). Normalise casing in one place before sending context.
• A segment with empty rules {} matches every non-empty context. This is useful as an "everyone" variant, so double-check it is intentional.
• rules is not validated at create time: values other than strings and arrays of strings are stored but never match. Keep rules to the two supported shapes.
• Assignment is attached to the flag UUID and does not travel down the key hierarchy: a segment on platform has no effect when you evaluate platform.auth. Attach segments to the exact keys you evaluate.

Notes

• Flags attach by flag_ids (UUIDs), not keys. Unknown fields in the request body are currently ignored, so a misspelled field has no effect and no error. Look up ids via GET /flags first.
• Variant assignment happens at event-write time from the event's context, matched against the experiment's segments (first match wins, in attachment order). Send the same context attributes you use for flag evaluation so variants line up with your rollout.
• Events logged while the experiment is draft/paused/completed are rejected with 400. Gate event emission on experiment state rather than buffering and retrying.
• user_id is your identifier and is deduplicated per variant (COUNT(DISTINCT user_id)); conversion requires the same id on funnel and goal events.
• Event names must exactly match goal_event/funnel_steps strings to be counted; unknown names are stored but excluded from analytics.
• Cross-org references are rejected atomically — attaching another organisation's segment or flag id rolls the whole create back with a 400.

Notes

• Inviting adds an existing Featrs account to your organisation; there is no email invitation flow for people without accounts yet.
• Plan-based limits are being introduced. Handle 403 responses from write endpoints (such as POST /flag and POST /user/invite) gracefully — they indicate a plan limit rather than a permissions problem.