Skip to content
Cloudflare API
Start here
API Reference
Flagship
Apps
Flags

Update flag

flagship.apps.flags.update(strflag_key, FlagUpdateParams**kwargs) -> FlagUpdateResponse
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. The path key identifies the flag and cannot be renamed by changing the body key. 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
ParametersExpand Collapse
account_id: str

Cloudflare account ID that owns the Flagship app.

app_id: str

Flagship app ID returned when the app was created.

flag_key: str

Case-sensitive key identifying the flag within the app.

default_variation: str

Variation the API serves when the flag is off, or when it’s on but no rule matches the context. Must be a key in variations.

minLength1
enabled: bool

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

key: str

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

maxLength64
minLength1
rules: Iterable[Rule]

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

conditions: Iterable[RuleCondition]

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

One of the following:
class RuleConditionUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
class RuleConditionUnionMember1: …
clauses: Iterable[RuleConditionUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
class RuleConditionUnionMember1ClauseUnionMember1: …
clauses: Iterable[RuleConditionUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: Iterable[RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: Iterable[RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: Iterable[RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: Sequence[Union[Optional[str], float, bool, 2 more]]
One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
priority: int

Evaluation order: the API evaluates rules with lower numbers first. Must be unique across the flag’s rules.

minimum1
serve_variation: str

Variation the API serves when this rule matches. Must be a key in variations.

minLength1
rollout: Optional[RuleRollout]
percentage: float

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

maximum100
minimum0
multipleOf0.01
attribute: Optional[str]

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

maxLength64
minLength1
variations: Dict[str, Union[Optional[str], float, bool, 2 more]]

Map of variation name to value. All values share the same type (boolean, string, number, or JSON object/array), and each serialized value stays within 10KB.

One of the following:
Optional[str]
float
bool
Dict[str, object]
Iterable[object]
description: Optional[str]

Optional operator-facing description. It does not affect flag evaluation.

maxLength512
Deprecatedtype: Optional[Literal["boolean", "string", "number", "json"]]

Deprecated compatibility field. Omit it; the API ignores this value and infers the type from the flag’s variations.

One of the following:
"boolean"
"string"
"number"
"json"
ReturnsExpand Collapse
class FlagUpdateResponse: …
default_variation: str

Variation the API serves when the flag is off, or when it’s on but no rule matches the context. Must be a key in variations.

minLength1
enabled: bool

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

key: str

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

maxLength64
minLength1
rules: List[Rule]

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

conditions: List[RuleCondition]

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

One of the following:
class RuleConditionUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
class RuleConditionUnionMember1: …
clauses: List[RuleConditionUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
class RuleConditionUnionMember1ClauseUnionMember1: …
clauses: List[RuleConditionUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: List[RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: List[RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: List[RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1Clause]
One of the following:
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember0: …
attribute: str
maxLength64
minLength1
operator: Literal["equals", "not_equals", "greater_than", 10 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"
"has"
"not_has"
value: Union[Optional[str], float, bool, 2 more]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
class RuleConditionUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1ClauseUnionMember1: …
clauses: List[Union[Optional[str], float, bool, 2 more]]
One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
logical_operator: Literal["AND", "OR"]
One of the following:
"AND"
"OR"
priority: int

Evaluation order: the API evaluates rules with lower numbers first. Must be unique across the flag’s rules.

minimum1
serve_variation: str

Variation the API serves when this rule matches. Must be a key in variations.

minLength1
rollout: Optional[RuleRollout]
percentage: float

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

maximum100
minimum0
multipleOf0.01
attribute: Optional[str]

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

maxLength64
minLength1
type: Literal["boolean", "string", "number", "json"]

Server-inferred value type shared by all of the flag’s variations.

One of the following:
"boolean"
"string"
"number"
"json"
variations: Dict[str, Union[Optional[str], float, bool, 2 more]]

Map of variation name to value. All values share the same type (boolean, string, number, or JSON object/array), and each serialized value stays within 10KB.

One of the following:
Optional[str]
float
bool
Dict[str, object]
List[object]
description: Optional[str]

Optional operator-facing description. It does not affect flag evaluation.

maxLength512
updated_at: Optional[str]
updated_by: Optional[str]

Update flag

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
flag = client.flagship.apps.flags.update(
    flag_key="flag_key",
    account_id="account_id",
    app_id="app_id",
    default_variation="x",
    enabled=True,
    key="x",
    rules=[{
        "conditions": [{
            "attribute": "x",
            "operator": "equals",
            "value": "string",
        }],
        "priority": 1,
        "serve_variation": "x",
    }],
    variations={
        "foo": "string"
    },
)
print(flag.default_variation)
{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "message"
    }
  ],
  "result": {
    "default_variation": "x",
    "enabled": true,
    "key": "x",
    "rules": [
      {
        "conditions": [
          {
            "attribute": "x",
            "operator": "equals",
            "value": "string"
          }
        ],
        "priority": 1,
        "serve_variation": "x",
        "rollout": {
          "percentage": 0,
          "attribute": "x"
        }
      }
    ],
    "type": "boolean",
    "variations": {
      "foo": "string"
    },
    "description": "description",
    "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": "string"
          }
        ],
        "priority": 1,
        "serve_variation": "x",
        "rollout": {
          "percentage": 0,
          "attribute": "x"
        }
      }
    ],
    "type": "boolean",
    "variations": {
      "foo": "string"
    },
    "description": "description",
    "updated_at": "updated_at",
    "updated_by": "updated_by"
  },
  "success": true
}