Featrs Integration Guide

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

Integrator notes

• Validation failures you might expect to be 409/422 often surface as 500 with a generic message — e.g. creating a flag whose key already exists trips the unique constraint and returns 500 Failed to create flag. Don't branch on message text; treat non-2xx as failure and retry only idempotent reads.
• Malformed JSON is rejected by the framework before the handler runs and returns a non-JSON error body — always check Content-Type of error responses before parsing.

# 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…"

Integrator notes

• Keep tokens server-side. A token grants full read/write access to the organisation. There is no browser-safe/client-side key type today, so evaluation from web or mobile clients must go through your own backend.
• Scopes are not enforced yet. You pass scopes when creating a key and they're embedded in the JWT, but no endpoint currently checks them — every valid token can call every org endpoint. Don't design around read-only keys until enforcement lands.
• Revocation is immediate. API-key tokens are re-validated against the database on every request, so revoking a key kills its outstanding tokens instantly (not just at the 1-hour expiry).
• Failed exchanges return 401 with distinct messages for invalid credentials, revoked, and expired keys.

Integrator notes

• Store the secret from the create response immediately; it cannot be retrieved again (only an Argon2 hash is stored).
• last_used_at is stamped on each successful token exchange (not on every API call), so it tells you 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 UI.

Integrator notes

• PUT /flag/{id} and POST /flag/{id}/dates are full replaces, not patches. Any optional field you omit is set to NULL. To clear an expiration date, send the body without it; to keep it, you must send it back. Read-modify-write if you only want to change one field.
• Creating a.b.c auto-creates missing ancestors a and a.b as enabled flags. If you don't want a live parent switch you didn't ask for, create parents explicitly first with the value you intend.
• Renaming a key via PUT does not rename children — hierarchy is purely string-based, so platform → core orphans every platform.* child from its old parent. Segment assignments and experiment links survive renames (they reference the flag UUID).
• Avoid / in keys: it makes the flag impossible to evaluate via the path-based GET endpoint (see below).
• percentage is not range-checked at the API layer; stick to 0–100 yourself.

# 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 }, … ]

Integrator notes

• Percentage rollouts are not sticky. Each evaluation is an independent random roll — there is no bucketing by user or context. A user under a 25% flag will see it flip on and off across requests. If you need a stable experience per user, evaluate once per session and cache the result yourself (and re-evaluate on your own cadence), or keep the flag at 0/100 and use segments for targeting instead.
• An empty or omitted context skips segment matching entirely and reports segment_match: true. Segments only gate users when you send at least one context attribute — "no context" is treated as "don't 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; watch /flags/stats for keys you don't recognise.
• segment_match is only meaningful from the single-flag context endpoint. The batch endpoint applies segment gating to enabled but doesn't return the flag-level 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 what you actually need at boot.
• Every evaluation writes an analytics row (asynchronously). At very high evaluation rates prefer the batch endpoint plus client-side caching over hammering per-request evaluation — evaluations are billed against the same capacity as the rest of the API.
• Circuit breakers exist in evaluation but there is no API to trip or reset them — they're operated directly in the database today. Treat "everything under a root suddenly false" as a possible deliberate trip.

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

Integrator notes

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

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

Integrator 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 — useful as an "everyone" variant, dangerous as an accident.
• rules accepts any JSON object; nothing validates that values are strings/arrays at create time. A malformed rule silently never matches.
• Assignment is attached to the flag UUID, so it does not travel down the key hierarchy: a segment on platform has no effect when you evaluate platform.auth (which resolves via its own flag or hierarchy fallback). Attach segments to the exact keys you evaluate.

Integrator notes

• Flags attach by flag_ids (UUIDs), not keys — the examples in older docs showing flag_keys are wrong. Unknown fields in the body are silently ignored, so a flag_keys payload "succeeds" with no flags attached. Look up ids via GET /flags first.
• Variant assignment happens at event-write time from the event's context, against the experiment's segments (first match wins, in attachment order). Send the same context attributes you use for flag evaluation, or your variants and your rollout won't line up.
• Events logged while the experiment is draft/paused/completed are rejected with 400 — buffer-and-retry on your side loses data unless the experiment is running again, so gate event emission on experiment state.
• user_id is your identifier and is deduplicated per variant (COUNT(DISTINCT user_id)); conversion needs 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 ignored by analytics.
• Cross-org references are rejected atomically — attaching another org's segment/flag id rolls the whole create back with a 400.

Integrator notes

• "Invite" is really "add an existing account to my org" — there is no email invitation flow for people without accounts yet.
• Plan limits are coming: on the Free tier, flag creation caps at 50 flags and invites are blocked (403 with an upgrade message); the Basic plan lifts both. Handle 403 from POST /flag gracefully.