Flagship API Reference

Binding API (Workers)

The binding is available as env.FLAGS (type Flagship from @cloudflare/workers-types).

Evaluation Methods

All methods are async, never throw, and return the defaultValue on errors.

Parameters (shared across all methods)

Types

type FlagshipEvaluationContext = Record<string, string | number | boolean>;

interface FlagshipEvaluationDetails<T> {
  flagKey: string;
  value: T;
  variant?: string;     // name of the matched variation
  reason?: string;      // "TARGETING_MATCH" | "DEFAULT" | "DISABLED" | "SPLIT"
  errorCode?: string;   // "TYPE_MISMATCH" | "GENERAL"
  errorMessage?: string;
}

Example

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const enabled = await env.FLAGS.getBooleanValue("new-feature", false, {
      userId: "user-42",
    });
    return new Response(enabled ? "Feature on" : "Feature off");
  },
};

OpenFeature SDK

Package: @cloudflare/flagship

Server Provider (FlagshipServerProvider)

For Workers, Node.js, and server-side JavaScript.

With binding (recommended inside Workers):

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship";

await OpenFeature.setProviderAndWait(
  new FlagshipServerProvider({ binding: env.FLAGS }),
);
const client = OpenFeature.getClient();
const enabled = await client.getBooleanValue("new-checkout", false, {
  targetingKey: "user-42",
});

With app ID (Node.js / non-Worker runtimes):

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship";

await OpenFeature.setProviderAndWait(
  new FlagshipServerProvider({
    appId: "<APP_ID>",
    accountId: "<ACCOUNT_ID>",
    authToken: "<API_TOKEN>",
  }),
);
const client = OpenFeature.getClient();
const enabled = await client.getBooleanValue("new-checkout", false, {
  targetingKey: "user-42",
});

Client Provider (FlagshipClientProvider)

For browser applications. Pre-fetches flags on init, evaluates synchronously.

import { OpenFeature } from "@openfeature/web-sdk";
import { FlagshipClientProvider } from "@cloudflare/flagship";

await OpenFeature.setProviderAndWait(
  new FlagshipClientProvider({
    appId: "<APP_ID>",
    accountId: "<ACCOUNT_ID>",
    authToken: "<API_TOKEN>",
    prefetchFlags: ["promo-banner", "dark-mode"],
  }),
);
await OpenFeature.setContext({ targetingKey: "user-42", plan: "enterprise" });
const client = OpenFeature.getClient();

// Synchronous — no await needed
const showBanner = client.getBooleanValue("promo-banner", false);

Important: Only flags listed in prefetchFlags are available. Unlisted flags return FLAG_NOT_FOUND.

SDK Hooks

import { LoggingHook, TelemetryHook } from "@cloudflare/flagship";
OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());

REST API (Flag Management)

FIRST: Check Prerequisites

Before making any REST API calls (create, read, update, delete, toggle flags), verify these environment variables are set:

Check with:

echo "CLOUDFLARE_ACCOUNT_ID=${CLOUDFLARE_ACCOUNT_ID:-(not set)}"
echo "CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN:-(not set)}"
echo "FLAGSHIP_APP_ID=${FLAGSHIP_APP_ID:-(not set)}"

If any are missing, ask the user to provide them before proceeding.

Base URL and Auth

Base URL: https://api.cloudflare.com/client/v4/accounts/{account_id}/flagship

Authentication: Authorization: Bearer <API_TOKEN>

Response envelope:

// Success
{ "success": true, "data": <T> }

// Error
{ "success": false, "error": "message" }

App Endpoints

App name constraints: alphanumeric + hyphens + underscores, 1-64 chars.

Flag Endpoints

Evaluate Endpoint

GET /apps/{app_id}/evaluate?flagKey=<key>&<context-attrs>

Requires an API token with flagship:evaluate permission. Context attributes passed as query params. Returns:

{
  "flagKey": "my-flag",
  "value": true,
  "variant": "on",
  "reason": "TARGETING_MATCH"
}

FlagDefinition Schema

{
  "key": "my-flag",
  "type": "boolean",
  "default_variation": "off",
  "variations": {
    "on": true,
    "off": false
  },
  "rules": [
    {
      "priority": 1,
      "conditions": [
        {
          "attribute": "email",
          "operator": "ends_with",
          "value": "@cloudflare.com"
        }
      ],
      "serve_variation": "on",
      "rollout": { "percentage": 100 }
    }
  ],
  "description": "Enables the new feature",
  "enabled": true
}

Field Constraints

Rule Schema

{
  "priority": 1,
  "conditions": [ /* Condition[] */ ],
  "serve_variation": "on",
  "rollout": { "percentage": 50, "attribute": "targetingKey" }
}

• priority: integer >= 1, unique across rules in the flag (lower = evaluated first)
• conditions: array of base or logical conditions
• serve_variation: must be a key in variations
• rollout: optional. percentage 0-100. attribute defaults to targetingKey.

Condition Schema

Base condition:

{ "attribute": "email", "operator": "ends_with", "value": "@cloudflare.com" }

Logical condition (AND/OR):

{
  "logical_operator": "AND",
  "clauses": [
    { "attribute": "country", "operator": "equals", "value": "US" },
    { "attribute": "plan", "operator": "in", "value": ["enterprise", "business"] }
  ]
}

Nesting supported up to 6 levels deep.

Operators

Rate Limits

Error Codes