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 
139### FIRST: Check Prerequisites
140 
141Before making any REST API calls (create, read, update, delete, toggle flags), verify these environment variables are set:
142 
143| Variable | Purpose | How to get |
144|----------|---------|------------|
145| `CLOUDFLARE_ACCOUNT_ID` | Account identifier | Dashboard URL or `wrangler whoami` |
146| `CLOUDFLARE_API_TOKEN` | Bearer token for API auth | [Create API token](https://dash.cloudflare.com/profile/api-tokens) with Flagship permissions |
147| `FLAGSHIP_APP_ID` | Target app UUID | Dashboard under **Compute > Flagship**, or `GET /apps` endpoint |
148 
149Check with:
150 
151```bash
152echo "CLOUDFLARE_ACCOUNT_ID=${CLOUDFLARE_ACCOUNT_ID:-(not set)}"
153echo "CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN:-(not set)}"
154echo "FLAGSHIP_APP_ID=${FLAGSHIP_APP_ID:-(not set)}"
155```
156 
157**If any are missing, ask the user to provide them before proceeding.**
158 
159### Base URL and Auth
160 
161Base URL: `https://api.cloudflare.com/client/v4/accounts/{account_id}/flagship`
162 
163Authentication: `Authorization: Bearer <API_TOKEN>`
164 
165Response envelope:
166 
167```json
168// Success
169{ "success": true, "data": <T> }
170 
171// Error
172{ "success": false, "error": "message" }
173```
174 
175### App Endpoints
176 
177| Method | Path | Description |
178|--------|------|-------------|
179| `GET` | `/apps` | List all apps |
180| `GET` | `/apps/{app_id}` | Get app |
181| `POST` | `/apps` | Create app (`{ "name": "my-app" }`) |
182| `PUT` | `/apps/{app_id}` | Update app (`{ "name": "new-name" }`) |
183| `DELETE` | `/apps/{app_id}` | Delete app |
184 
185App name constraints: alphanumeric + hyphens + underscores, 1-64 chars.
186 
187### Flag Endpoints
188 
189| Method | Path | Description |
190|--------|------|-------------|
191| `GET` | `/apps/{app_id}/flags?limit=50&cursor=<cursor>` | List flags (paginated) |
192| `GET` | `/apps/{app_id}/flags/{flag_key}` | Get flag |
193| `POST` | `/apps/{app_id}/flags` | Create flag |
194| `PUT` | `/apps/{app_id}/flags/{flag_key}` | Update flag (full replace) |
195| `DELETE` | `/apps/{app_id}/flags/{flag_key}` | Delete flag |
196| `GET` | `/apps/{app_id}/flags/{flag_key}/changelog?limit=20&cursor=<cursor>` | Flag changelog |
197 
198### Evaluate Endpoint
199 
200```
201GET /apps/{app_id}/evaluate?flagKey=<key>&<context-attrs>
202```
203 
204Requires an API token with `flagship:evaluate` permission. Context attributes passed as query params. Returns:
205 
206```json
207{
208  "flagKey": "my-flag",
209  "value": true,
210  "variant": "on",
211  "reason": "TARGETING_MATCH"
212}
213```
214 
215---
216 
217## FlagDefinition Schema
218 
219```json
220{
221  "key": "my-flag",
222  "type": "boolean",
223  "default_variation": "off",
224  "variations": {
225    "on": true,
226    "off": false
227  },
228  "rules": [
229    {
230      "priority": 1,
231      "conditions": [
232        {
233          "attribute": "email",
234          "operator": "ends_with",
235          "value": "@cloudflare.com"
236        }
237      ],
238      "serve_variation": "on",
239      "rollout": { "percentage": 100 }
240    }
241  ],
242  "description": "Enables the new feature",
243  "enabled": true
244}
245```
246 
247### Field Constraints
248 
249| Field | Type | Constraints |
250|-------|------|-------------|
251| `key` | string | 1-64 chars, `/^[a-zA-Z0-9_-]+$/` |
252| `type` | enum | Optional. `boolean`, `string`, `number`, `json` (auto-inferred from variations) |
253| `default_variation` | string | Must be a key in `variations` |
254| `variations` | `Record<string, T>` | At least one. All values same type. Keys: alphanumeric/hyphens/underscores, max 64 chars. Values max 10KB. |
255| `rules` | `Rule[]` | Can be empty. No duplicate priorities. |
256| `description` | string? | Max 512 chars, nullable |
257| `enabled` | boolean | Required. `false` = always returns default variation. |
258 
259### Rule Schema
260 
261```json
262{
263  "priority": 1,
264  "conditions": [ /* Condition[] */ ],
265  "serve_variation": "on",
266  "rollout": { "percentage": 50, "attribute": "targetingKey" }
267}
268```
269 
270- `priority`: integer >= 1, unique across rules in the flag (lower = evaluated first)
271- `conditions`: array of base or logical conditions
272- `serve_variation`: must be a key in `variations`
273- `rollout`: optional. `percentage` 0-100. `attribute` defaults to `targetingKey`.
274 
275### Condition Schema
276 
277**Base condition:**
278 
279```json
280{ "attribute": "email", "operator": "ends_with", "value": "@cloudflare.com" }
281```
282 
283**Logical condition (AND/OR):**
284 
285```json
286{
287  "logical_operator": "AND",
288  "clauses": [
289    { "attribute": "country", "operator": "equals", "value": "US" },
290    { "attribute": "plan", "operator": "in", "value": ["enterprise", "business"] }
291  ]
292}
293```
294 
295Nesting supported up to 6 levels deep.
296 
297### Operators
298 
299| Operator | Description | Value Type |
300|----------|-------------|------------|
301| `equals` | Exact match (case-sensitive) | String |
302| `not_equals` | Not exact match | String |
303| `greater_than` | Numeric / datetime > | Number, ISO 8601 |
304| `less_than` | Numeric / datetime < | Number, ISO 8601 |
305| `greater_than_or_equals` | >= | Number, ISO 8601 |
306| `less_than_or_equals` | <= | Number, ISO 8601 |
307| `contains` | Substring match (case-sensitive) | String |
308| `starts_with` | Prefix match | String |
309| `ends_with` | Suffix match | String |
310| `in` | Value in array | Array |
311| `not_in` | Value not in array | Array |
312 
313---
314 
315## Rate Limits
316 
317| Operation | Limit |
318|-----------|-------|
319| Mutations (POST/PUT/DELETE) | 60 per 60s per account:app |
320| Reads (GET) | 600 per 60s per account:app |
321 
322## Error Codes
323 
324| HTTP Status | Meaning |
325|-------------|---------|
326| 200 | Success (read/update/delete) |
327| 201 | Created (create) |
328| 400 | Validation error (check `error` field) |
329| 401 | Invalid or missing token |
330| 404 | Flag or app not found |
331| 409 | Flag key already exists (create) |
332| 429 | Rate limited |
333