SDK Quickstart (Raw HTTP)

If you're using React, use the published React SDK (npm install flagpulse-react) instead of calling the API directly — it handles caching, headers, and realtime updates for you.

This page documents the underlying HTTP contract the React SDK (and any future SDK for another language/framework) is built on — useful if you're on a stack without an official SDK yet, or you're debugging what the SDK is doing under the hood.

Get your SDK key

Every environment has its own SDK key, shown on that environment's page in the dashboard (or returned by rotating it).

Keep environment keys separate

An SDK key only unlocks flags for its own environment. Using a staging key in production (or vice versa) will evaluate the wrong flag set — there's no cross-environment protection beyond using the right key.

Fetch flags

GET /api/v1/flags
Header: x-sdk-key: <your environment's SDK key>

Response — an array of every flag defined for that environment, with the environment's current values already merged in:

[
  {
    "flag_id": "5b1c...",
    "key": "new-checkout-flow",
    "name": "New checkout flow",
    "type": "boolean",
    "is_enabled": true,
    "rollout_percentage": 25,
    "targeting_attribute": "userId",
    "targeting_value": null,
    "targeting_return_value": null
  }
]

There's no per-flag GET-by-key endpoint — fetch the full array and look up by key client-side. A minimal client:

async function getFlags(sdkKey) {
  const res = await fetch("https://your-flagpulse-host/api/v1/flags", {
    headers: { "x-sdk-key": sdkKey },
  });
  if (res.status === 401) throw new Error("Invalid or revoked SDK key");
  return res.json(); // Flag[]
}

function isEnabled(flags, key) {
  return flags.find(f => f.key === key)?.is_enabled ?? false;
}

Evaluation is server-computed, not client-computed

FlagPulse returns the resolved is_enabled/rollout_percentage/targeting_* fields as stored — it does not currently evaluate rollout percentage or targeting rules against a specific user on the server. If you need per-user rollout/targeting decisions, your application code should apply rollout_percentage and targeting_attribute/targeting_value/targeting_return_value against the current request's context after fetching the flag.

CORS

Browser-based SDK calls are only permitted from origins registered as an environment's URL (see Architecture → Dynamic per-project CORS). Server-side calls (no Origin header) are always allowed. If a browser call is unexpectedly blocked, check that the calling origin exactly matches the environment's configured URL.

Caching behavior to expect

Responses are served from a 5-minute Redis cache per environment and invalidated immediately on any write from the dashboard/API. In practice this means: a flag change is visible to a fresh GET /api/v1/flags call right away — the cache is a performance layer, not a source of staleness for polling clients. For push-based updates instead of polling, see Realtime Updates.