1# Flagship API Reference
2 
3## Binding API (Workers)
4 
5The binding is available as `env.FLAGS` (type `Flagship` from `@cloudflare/workers-types`).
6 
7### Evaluation Methods
8 
9All methods are async, never throw, and return the `defaultValue` on errors.
10 
11| Method | Signature | Returns |
12|--------|-----------|---------|
13| `get` | `get(flagKey, defaultValue?, context?)` | `Promise<unknown>` |
14| `getBooleanValue` | `getBooleanValue(flagKey, defaultValue, context?)` | `Promise<boolean>` |
15| `getStringValue` | `getStringValue(flagKey, defaultValue, context?)` | `Promise<string>` |
16| `getNumberValue` | `getNumberValue(flagKey, defaultValue, context?)` | `Promise<number>` |
17| `getObjectValue` | `getObjectValue<T>(flagKey, defaultValue, context?)` | `Promise<T>` |
18| `getBooleanDetails` | `getBooleanDetails(flagKey, defaultValue, context?)` | `Promise<FlagshipEvaluationDetails<boolean>>` |
19| `getStringDetails` | `getStringDetails(flagKey, defaultValue, context?)` | `Promise<FlagshipEvaluationDetails<string>>` |
20| `getNumberDetails` | `getNumberDetails(flagKey, defaultValue, context?)` | `Promise<FlagshipEvaluationDetails<number>>` |
21| `getObjectDetails` | `getObjectDetails<T>(flagKey, defaultValue, context?)` | `Promise<FlagshipEvaluationDetails<T>>` |
22 
23### Parameters (shared across all methods)
24 
25| Parameter | Type | Required | Description |
26|-----------|------|----------|-------------|
27| `flagKey` | `string` | Yes | Flag key to evaluate |
28| `defaultValue` | varies | Yes (except `get`) | Fallback if evaluation fails or flag not found |
29| `context` | `FlagshipEvaluationContext` | No | Attributes for targeting rules (`{ userId: "user-42", country: "US" }`) |
30 
31### Types
32 
33```typescript
34type FlagshipEvaluationContext = Record<string, string | number | boolean>;
35 
36interface FlagshipEvaluationDetails<T> {
37  flagKey: string;
38  value: T;
39  variant?: string;     // name of the matched variation
40  reason?: string;      // "TARGETING_MATCH" | "DEFAULT" | "DISABLED" | "SPLIT"
41  errorCode?: string;   // "TYPE_MISMATCH" | "GENERAL"
42  errorMessage?: string;
43}
44```
45 
46### Example
47 
48```typescript
49export default {
50  async fetch(request: Request, env: Env): Promise<Response> {
51    const enabled = await env.FLAGS.getBooleanValue("new-feature", false, {
52      userId: "user-42",
53    });
54    return new Response(enabled ? "Feature on" : "Feature off");
55  },
56};
57```
58 
59---
60 
61## OpenFeature SDK
62 
63Package: `@cloudflare/flagship`
64 
65### Server Provider (`FlagshipServerProvider`)
66 
67For Workers, Node.js, and server-side JavaScript.
68 
69**With binding (recommended inside Workers):**
70 
71```typescript
72import { OpenFeature } from "@openfeature/server-sdk";
73import { FlagshipServerProvider } from "@cloudflare/flagship";
74 
75await OpenFeature.setProviderAndWait(
76  new FlagshipServerProvider({ binding: env.FLAGS }),
77);
78const client = OpenFeature.getClient();
79const enabled = await client.getBooleanValue("new-checkout", false, {
80  targetingKey: "user-42",
81});
82```
83 
84**With app ID (Node.js / non-Worker runtimes):**
85 
86```typescript
87import { OpenFeature } from "@openfeature/server-sdk";
88import { FlagshipServerProvider } from "@cloudflare/flagship";
89 
90await OpenFeature.setProviderAndWait(
91  new FlagshipServerProvider({
92    appId: "<APP_ID>",
93    accountId: "<ACCOUNT_ID>",
94    authToken: "<API_TOKEN>",
95  }),
96);
97const client = OpenFeature.getClient();
98const enabled = await client.getBooleanValue("new-checkout", false, {
99  targetingKey: "user-42",
100});
101```
102 
103### Client Provider (`FlagshipClientProvider`)
104 
105For browser applications. Pre-fetches flags on init, evaluates synchronously.
106 
107```typescript
108import { OpenFeature } from "@openfeature/web-sdk";
109import { FlagshipClientProvider } from "@cloudflare/flagship";
110 
111await OpenFeature.setProviderAndWait(
112  new FlagshipClientProvider({
113    appId: "<APP_ID>",
114    accountId: "<ACCOUNT_ID>",
115    authToken: "<API_TOKEN>",
116    prefetchFlags: ["promo-banner", "dark-mode"],
117  }),
118);
119await OpenFeature.setContext({ targetingKey: "user-42", plan: "enterprise" });
120const client = OpenFeature.getClient();
121 
122// Synchronous — no await needed
123const showBanner = client.getBooleanValue("promo-banner", false);
124```
125 
126**Important:** Only flags listed in `prefetchFlags` are available. Unlisted flags return `FLAG_NOT_FOUND`.
127 
128### SDK Hooks
129 
130```typescript
131import { LoggingHook, TelemetryHook } from "@cloudflare/flagship";
132OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());
133```
134 
135---
136 
137## REST API (Flag Management)
138 
139Source of truth: [Cloudflare Flagship API reference](https://developers.cloudflare.com/api/resources/flagship/). Use it to verify REST paths, envelopes, response fields, and permission wording before relying on examples here.
140 
141### FIRST: Check Prerequisites
142 
143Before making any REST API calls (create, read, update, delete, toggle flags), verify these environment variables are set:
144 
145| Variable | Purpose | How to get |
146|----------|---------|------------|
147| `CLOUDFLARE_ACCOUNT_ID` | Account identifier | Dashboard URL or `wrangler whoami` |
148| `CLOUDFLARE_API_TOKEN` | Bearer token for API auth | [Create API token](https://dash.cloudflare.com/profile/api-tokens) with Flagship permissions |
149| `FLAGSHIP_APP_ID` | Target app UUID | Dashboard under **Compute > Flagship**, or `GET /apps` endpoint |
150 
151Check with:
152 
153```bash
154echo "CLOUDFLARE_ACCOUNT_ID=${CLOUDFLARE_ACCOUNT_ID:-(not set)}"
155echo "CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN:-(not set)}"
156echo "FLAGSHIP_APP_ID=${FLAGSHIP_APP_ID:-(not set)}"
157```
158 
159**If any are missing, ask the user to provide them before proceeding.**
160 
161### Base URL and Auth
162 
163Base URL: `https://api.cloudflare.com/client/v4/accounts/{account_id}/flagship`
164 
165Authentication: `Authorization: Bearer <API_TOKEN>`
166 
167Management endpoints use the Cloudflare v4 envelope. On success, the payload is under `result`; errors are an array under `errors`.
168 
169```jsonc
170// Success
171{ "success": true, "result": <T>, "errors": [], "messages": [] }
172 
173// Paginated success
174{
175  "success": true,
176  "result": [<T>],
177  "result_info": { "count": 50, "cursor": "next-cursor-or-null" },
178  "errors": [],
179  "messages": []
180}
181 
182// Error
183{ "success": false, "result": null, "errors": [{ "message": "message" }], "messages": [] }
184```
185 
186### App Endpoints
187 
188| Method | Path | Description |
189|--------|------|-------------|
190| `GET` | `/apps` | List all apps |
191| `GET` | `/apps/{app_id}` | Get app |
192| `POST` | `/apps` | Create app (`{ "name": "my-app" }`) |
193| `PUT` | `/apps/{app_id}` | Update app (`{ "name": "new-name" }`) |
194| `DELETE` | `/apps/{app_id}` | Delete app |
195 
196App name constraints: alphanumeric + hyphens + underscores, 1-64 chars.
197 
198### Flag Endpoints
199 
200| Method | Path | Description |
201|--------|------|-------------|
202| `GET` | `/apps/{app_id}/flags?limit=50&cursor=<cursor>` | List flags (paginated) |
203| `GET` | `/apps/{app_id}/flags/{flag_key}` | Get flag |
204| `POST` | `/apps/{app_id}/flags` | Create flag |
205| `PUT` | `/apps/{app_id}/flags/{flag_key}` | Update flag (full replace) |
206| `DELETE` | `/apps/{app_id}/flags/{flag_key}` | Delete flag |
207| `GET` | `/apps/{app_id}/flags/{flag_key}/changelog?limit=20&cursor=<cursor>` | Flag changelog |
208 
209### Evaluate Endpoint
210 
211```
212GET /apps/{app_id}/evaluate?flagKey=<key>&<context-attrs>
213```
214 
215Requires an API token with the `com.cloudflare.account.flagship.evaluate` permission. Context attributes passed as query params. This endpoint is not wrapped in the management envelope; the SDK contract returns OpenFeature-style camelCase:
216 
217```json
218{
219  "flagKey": "my-flag",
220  "value": true,
221  "variant": "on",
222  "reason": "SPLIT"
223}
224```
225 
226Reasons: `TARGETING_MATCH`, `SPLIT`, `DEFAULT`, `DISABLED`.
227 
228### Management Response Payloads
229 
230Management endpoints are wrapped in the Cloudflare v4 envelope shown above. Common `.result` payloads:
231 
232**App result**
233 
234```json
235{
236  "id": "app-uuid",
237  "name": "my-app",
238  "created_at": "2026-06-09T12:00:00.000Z",
239  "updated_at": "2026-06-09T12:00:00.000Z",
240  "updated_by": "[email protected]"
241}
242```
243 
244**Flag result**
245 
246```json
247{
248  "key": "my-flag",
249  "type": "boolean",
250  "default_variation": "off",
251  "variations": { "on": true, "off": false },
252  "rules": [],
253  "description": "Enables the new feature",
254  "enabled": true,
255  "updated_at": "2026-06-09T12:00:00.000Z",
256  "updated_by": "[email protected]"
257}
258```
259 
260**Changelog entry**
261 
262```json
263{
264  "flag_key": "my-flag",
265  "event": "update",
266  "after": { "key": "my-flag", "default_variation": "off", "variations": { "on": true, "off": false }, "rules": [], "enabled": true },
267  "diff": { "enabled": { "from": false, "to": true } }
268}
269```
270 
271Changelog entries include the full flag state after the change. `update` entries also include `diff`.
272 
273---
274 
275## FlagDefinition Schema
276 
277```json
278{
279  "key": "my-flag",
280  "type": "boolean",
281  "default_variation": "off",
282  "variations": {
283    "on": true,
284    "off": false
285  },
286  "rules": [
287    {
288      "priority": 1,
289      "conditions": [
290        {
291          "attribute": "email",
292          "operator": "ends_with",
293          "value": "@cloudflare.com"
294        }
295      ],
296      "serve_variation": "on",
297      "rollout": { "percentage": 100 }
298    }
299  ],
300  "description": "Enables the new feature",
301  "enabled": true
302}
303```
304 
305### Field Constraints
306 
307| Field | Type | Constraints |
308|-------|------|-------------|
309| `key` | string | 1-64 chars, `/^[a-zA-Z0-9_-]+$/` |
310| `type` | enum | Optional. `boolean`, `string`, `number`, `json` (auto-inferred from variations) |
311| `default_variation` | string | Must be a key in `variations` |
312| `variations` | `Record<string, T>` | At least one. All values same type. Keys: alphanumeric/hyphens/underscores, max 64 chars. Values max 10KB. |
313| `rules` | `Rule[]` | Can be empty. No duplicate priorities. |
314| `description` | string? | Max 512 chars, nullable |
315| `enabled` | boolean | Required. `false` = always returns default variation. |
316 
317### Rule Schema
318 
319```json
320{
321  "priority": 1,
322  "conditions": [ /* Condition[] */ ],
323  "serve_variation": "on",
324  "rollout": { "percentage": 50, "attribute": "targetingKey" }
325}
326```
327 
328- `priority`: integer >= 1, unique across rules in the flag (lower = evaluated first)
329- `conditions`: array of base or logical conditions
330- `serve_variation`: must be a key in `variations`
331- `rollout`: optional. `percentage` 0-100. `attribute` defaults to `targetingKey`.
332 
333### Condition Schema
334 
335**Base condition:**
336 
337```json
338{ "attribute": "email", "operator": "ends_with", "value": "@cloudflare.com" }
339```
340 
341**Logical condition (AND/OR):**
342 
343```json
344{
345  "logical_operator": "AND",
346  "clauses": [
347    { "attribute": "country", "operator": "equals", "value": "US" },
348    { "attribute": "plan", "operator": "in", "value": ["enterprise", "business"] }
349  ]
350}
351```
352 
353Nesting supported up to 6 levels deep.
354 
355### Operators
356 
357| Operator | Description | Value Type |
358|----------|-------------|------------|
359| `equals` | Exact match (case-sensitive) | String |
360| `not_equals` | Not exact match | String |
361| `greater_than` | Numeric / datetime > | Number, ISO 8601 |
362| `less_than` | Numeric / datetime < | Number, ISO 8601 |
363| `greater_than_or_equals` | >= | Number, ISO 8601 |
364| `less_than_or_equals` | <= | Number, ISO 8601 |
365| `contains` | Substring match (case-sensitive) | String |
366| `starts_with` | Prefix match | String |
367| `ends_with` | Suffix match | String |
368| `in` | Value in array | Array |
369| `not_in` | Value not in array | Array |
370 
371---
372 
373## Rate Limits
374 
375| Operation | Limit |
376|-----------|-------|
377| Mutations (POST/PUT/DELETE) | 60 per 60s per account:app |
378| Reads (GET) | 600 per 60s per account:app |
379 
380## Error Codes
381 
382| HTTP Status | Meaning |
383|-------------|---------|
384| 200 | Success (read/update/delete) |
385| 201 | Created (create) |
386| 400 | Validation error (check `errors[].message`) |
387| 401 | Invalid or missing token |
388| 404 | Flag or app not found |
389| 409 | Flag key already exists (create) |
390| 429 | Rate limited |
391