Create flag

client.flagship.apps.flags.create(, , ?): FlagCreateResponse { default_variation, enabled, key, 6 more }

POST/accounts/{account_id}/flagship/apps/{app_id}/flags

Creates a flag. Returns 409 if the key already exists. type is inferred from variation values and may be omitted.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Flagship Write

ParametersExpand Collapse

appId: string

App identifier.

params: FlagCreateParams { account_id, default_variation, enabled, 5 more }

account_id: string

Path param: Cloudflare account ID.

default_variation: string

Body param: Variation served when no rule matches or the flag is disabled. Must be a key in variations.

minLength1

enabled: boolean

Body param: When false, the flag bypasses all rules and always serves default_variation.

key: string

Body param: Unique identifier for the flag within an app. Used in all evaluation and SDK calls.

maxLength64

minLength1

rules: Array<Rule>

Body param: Targeting rules evaluated in ascending priority; the first matching rule wins. An empty array means the flag always serves default_variation.

conditions: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

Conditions the context must satisfy for this rule to match. An empty array matches all contexts.

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<string | null | number | boolean | 2 more>

One of the following:

string | null

number

boolean

Record<string, unknown>

Array<unknown>

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

priority: number

Evaluation order; lower numbers are evaluated first. Must be unique across the flag’s rules.

minimum1

serve_variation: string

Variation served when this rule matches. Must be a key in variations.

minLength1

rollout?: Rollout { percentage, attribute }

percentage: number

Percentage of matching traffic (0–100) served this variation. For multi-way splits, use cumulative upper bounds across rules (e.g. 30, 70, 100).

maximum100

minimum0

attribute?: string

Context attribute used for sticky bucketing. Defaults to targetingKey. If absent at evaluation time, bucketing is random per request.

minLength1

variations: Record<string, string | null | number | boolean | 2 more>

Body param: Map of variation name to value. All values must be the same type (boolean, string, number, or JSON object/array). Each serialized value must be 10KB or smaller.

One of the following:

string | null

number

boolean

Record<string, unknown>

Array<unknown>

description?: string | null

Body param

maxLength512

type?: "boolean" | "string" | "number" | "json"

Body param: Value type of the flag’s variations. Inferred from the variation values on write, so it may be omitted in requests.

One of the following:

"boolean"

"string"

"number"

"json"

ReturnsExpand Collapse

FlagCreateResponse { default_variation, enabled, key, 6 more }

default_variation: string

Variation served when no rule matches or the flag is disabled. Must be a key in variations.

minLength1

enabled: boolean

When false, the flag bypasses all rules and always serves default_variation.

key: string

Unique identifier for the flag within an app. Used in all evaluation and SDK calls.

maxLength64

minLength1

rules: Array<Rule>

Targeting rules evaluated in ascending priority; the first matching rule wins. An empty array means the flag always serves default_variation.

conditions: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

Conditions the context must satisfy for this rule to match. An empty array matches all contexts.

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<UnionMember0 { attribute, operator, value } | UnionMember1 { clauses, logical_operator } >

One of the following:

UnionMember0 { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" | "not_equals" | "greater_than" | 8 more

One of the following:

"equals"

"not_equals"

"greater_than"

"less_than"

"greater_than_or_equals"

"less_than_or_equals"

"contains"

"starts_with"

"ends_with"

"in"

"not_in"

value: unknown

Value to compare against the context attribute. Must be an array for in and not_in; numeric and ISO-8601 datetime strings are accepted by the ordering operators.

UnionMember1 { clauses, logical_operator }

clauses: Array<string | null | number | boolean | 2 more>

One of the following:

string | null

number

boolean

Record<string, unknown>

Array<unknown>

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" | "OR"

One of the following:

"AND"

"OR"

priority: number

Evaluation order; lower numbers are evaluated first. Must be unique across the flag’s rules.

minimum1

serve_variation: string

Variation served when this rule matches. Must be a key in variations.

minLength1

rollout?: Rollout { percentage, attribute }

percentage: number

Percentage of matching traffic (0–100) served this variation. For multi-way splits, use cumulative upper bounds across rules (e.g. 30, 70, 100).

maximum100

minimum0

attribute?: string

Context attribute used for sticky bucketing. Defaults to targetingKey. If absent at evaluation time, bucketing is random per request.

minLength1

variations: Record<string, string | null | number | boolean | 2 more>

Map of variation name to value. All values must be the same type (boolean, string, number, or JSON object/array). Each serialized value must be 10KB or smaller.

One of the following:

string | null

number

boolean

Record<string, unknown>

Array<unknown>

description?: string | null

maxLength512

type?: "boolean" | "string" | "number" | "json"

Value type of the flag’s variations. Inferred from the variation values on write, so it may be omitted in requests.

One of the following:

"boolean"

"string"

"number"

"json"

updated_at?: string

updated_by?: string

Create flag

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const flag = await client.flagship.apps.flags.create('app_id', {
  account_id: 'account_id',
  default_variation: 'x',
  enabled: true,
  key: 'x',
  rules: [
    {
      conditions: [
        {
          attribute: 'x',
          operator: 'equals',
          value: {},
        },
      ],
      priority: 1,
      serve_variation: 'x',
    },
  ],
  variations: { foo: 'string' },
});

console.log(flag.default_variation);

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "message"
    }
  ],
  "result": {
    "default_variation": "x",
    "enabled": true,
    "key": "x",
    "rules": [
      {
        "conditions": [
          {
            "attribute": "x",
            "operator": "equals",
            "value": {}
          }
        ],
        "priority": 1,
        "serve_variation": "x",
        "rollout": {
          "percentage": 0,
          "attribute": "x"
        }
      }
    ],
    "variations": {
      "foo": "string"
    },
    "description": "description",
    "type": "boolean",
    "updated_at": "updated_at",
    "updated_by": "updated_by"
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "message"
    }
  ],
  "result": {
    "default_variation": "x",
    "enabled": true,
    "key": "x",
    "rules": [
      {
        "conditions": [
          {
            "attribute": "x",
            "operator": "equals",
            "value": {}
          }
        ],
        "priority": 1,
        "serve_variation": "x",
        "rollout": {
          "percentage": 0,
          "attribute": "x"
        }
      }
    ],
    "variations": {
      "foo": "string"
    },
    "description": "description",
    "type": "boolean",
    "updated_at": "updated_at",
    "updated_by": "updated_by"
  },
  "success": true
}