Update flag

PUT/accounts/{account_id}/flagship/apps/{app_id}/flags/{flag_key}

Replaces the entire flag definition. Omitted fields are dropped, not preserved — read before writing. Each update appends a changelog entry.

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

Path ParametersExpand Collapse

account_id: string

Cloudflare account ID.

app_id: string

App identifier.

flag_key: string

Flag key (slug).

Body ParametersJSONExpand Collapse

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 of object { conditions, priority, serve_variation, rollout }

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

conditions: array of object { attribute, operator, value } or object { clauses, logical_operator }

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

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of string or number or boolean or 2 more

One of the following:

string

number

boolean

map[unknown]

array of unknown

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "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: optional object { 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: optional string

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

minLength1

variations: map[string or number or boolean or 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

number

boolean

map[unknown]

array of unknown

description: optional string

maxLength512

type: optional "boolean" or "string" or "number" or "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"

ReturnsExpand Collapse

errors: array of object { message }

message: string

messages: array of object { message }

message: string

result: object { 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 of object { conditions, priority, serve_variation, rollout }

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

conditions: array of object { attribute, operator, value } or object { clauses, logical_operator }

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

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of object { attribute, operator, value } or object { clauses, logical_operator }

One of the following:

object { attribute, operator, value }

attribute: string

maxLength64

minLength1

operator: "equals" or "not_equals" or "greater_than" or 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.

object { clauses, logical_operator }

clauses: array of string or number or boolean or 2 more

One of the following:

string

number

boolean

map[unknown]

array of unknown

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "OR"

One of the following:

"AND"

"OR"

logical_operator: "AND" or "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: optional object { 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: optional string

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

minLength1

variations: map[string or number or boolean or 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

number

boolean

map[unknown]

array of unknown

description: optional string

maxLength512

type: optional "boolean" or "string" or "number" or "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: optional string

updated_by: optional string

success: boolean

Update flag

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/flagship/apps/$APP_ID/flags/$FLAG_KEY \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "default_variation": "x",
          "enabled": true,
          "key": "x",
          "rules": [
            {
              "conditions": [
                {
                  "attribute": "x",
                  "operator": "equals",
                  "value": {}
                }
              ],
              "priority": 1,
              "serve_variation": "x"
            }
          ],
          "variations": {
            "foo": "string"
          }
        }'

{
  "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
}