Documentation

Everything you need to integrate OnlyFlags.

The __id field

Every evaluation request includes a user context object. The __id field is the only mandatory key — it uniquely identifies the entity being evaluated and is used for consistent targeting and percentage rollouts.

{ __id: "user-123", plan: "premium", role: "admin" }

It must be stable — the same entity should always send the same __id so a user who got variant-b yesterday still gets it today.

Tip — anonymous users

No logged-in user ID? Use a hash of the user agent + IP address to produce a deterministic __id without requiring authentication.

OnlyFlags also auto-injects geolocation fields from Cloudflare (cf_country, cf_region, cf_timezone, cf_isEu) — no need to send these yourself.

Speed vs. propagation

OnlyFlags evaluates flags at the edge across 300+ locations worldwide. When you update a flag, the change applies instantly for requests hitting the same region.

Propagation across different regions may take up to 1–2 minutes as the update reaches all edge locations. During that window, users in other regions may still see the previous flag value.

1–2 min

Propagation time across regions

For most use cases — gradual rollouts, A/B tests, feature gates — this is invisible to users. Changes are instant where they originate and propagate globally within minutes.

Copy. Paste. Ship.

Real code. Works in any stack. No SDK lock-in. 

import { useQuery } from "@tanstack/react-query";

type FeatureFlags = {
  darkMode?: string;
};

const fetchFlags = (ctx: string): Promise<FeatureFlags> =>
  fetch(`https://eval.onlyflags.app/${PROJECT_KEY}/${ctx}`)
    .then((r) => r.json());

function useFlags(userContext: Record<string, string>) {
  const ctx = btoa(JSON.stringify(userContext));

  return useQuery<FeatureFlags>({
    queryKey: ["flags", ctx],
    queryFn: () => fetchFlags(ctx),
    staleTime: 15_000,
  });
}

// Inside your component
const { data: flags } = useFlags({ __id: "user-123", plan: "premium" });

if (flags?.darkMode === "activated") {
  enableDarkMode();
}

Start for free. Scale when you're ready.

No credit card. No startup tax. Start building in minutes.

Create your first flag