Flag configurations API

The Flag Configurations API allows you to manage per-environment flag settings, including default values, targeting conditions, and rollout configurations.

Get flag configuration

Retrieves the configuration for a flag in a specific environment.

Request

GET /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID.
`flagId`	string	Required. The flag ID.
`environmentId`	string	Required. The environment ID.

applicationId

string

Required. The application ID.

flagId

string

Required. The flag ID.

environmentId

string

Required. The environment ID.

Response

{
  "configuration": {
    "enabled": true,
    "defaultValue": false,
    "conditions": [
      {
        "allOf": [
          {
            "allOf": [
              {
                "group": {
                  "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
                }
              }
            ]
          }
        ],
        "flagValue": true
      }
    ],
    "stickinessProperty": "user_id",
    "variantsEnabled": false,
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-02-01T14:22:00Z"
  }
}▼

Example

curl -X GET \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c/configuration/environments/e5c8d3e0-9f6b-5d4f-c2e7-b0f4e8d6c9e3" \
  -H "Authorization: Bearer YOUR_TOKEN"▼

Update flag configuration

Updates the complete configuration for a flag in a specific environment.

Request

PUT /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID.
`flagId`	string	Required. The flag ID.
`environmentId`	string	Required. The environment ID.

applicationId

string

Required. The application ID.

flagId

string

Required. The flag ID.

environmentId

string

Required. The environment ID.

Request body

{
  "enabled": true,
  "defaultValue": false,
  "conditions": [
    {
      "allOf": [
        {
          "allOf": [
            {
              "group": {
                "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
              }
            }
          ]
        }
      ],
      "flagValue": true
    },
    {
      "allOf": [
        {
          "allOf": [
            {
              "group": {
                "id": "a8f5b2c9-7e4d-4a1c-9b6e-3f8d7c5e4b2a"
              }
            }
          ]
        }
      ],
      "flagValue": true
    }
  ],
  "stickinessProperty": "user_id"
}▼

Field Type Required Description

Field	Type	Required	Description
`enabled`	boolean	No	Whether the flag is enabled in this environment.
`defaultValue`	any	No	Default value when no conditions match.
`conditions`	array	No	Array of targeting conditions (evaluated in order).
`stickinessProperty`	string	No	Property for consistent percentage-based evaluation.
`variantsEnabled`	boolean	No	Whether multiple variants are enabled.

enabled

boolean

Whether the flag is enabled in this environment.

defaultValue

any

Default value when no conditions match.

conditions

array

Array of targeting conditions (evaluated in order).

stickinessProperty

string

Property for consistent percentage-based evaluation.

variantsEnabled

boolean

Whether multiple variants are enabled.

Response

Returns the updated configuration.

Example

curl -X PUT \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c/configuration/environments/e5c8d3e0-9f6b-5d4f-c2e7-b0f4e8d6c9e3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "defaultValue": false,
    "conditions": [
      {
        "allOf": [
          {
            "allOf": [
              {
                "group": {
                  "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
                }
              }
            ]
          }
        ],
        "flagValue": true
      }
    ]
  }'▼

Patch flag configuration

Partially updates a flag configuration. Only specified fields are updated.

Request

PATCH /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}▼

Request body

Include only the fields you want to update:

{
  "enabled": false
}▼

Example

curl -X PATCH \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c/configuration/environments/e5c8d3e0-9f6b-5d4f-c2e7-b0f4e8d6c9e3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'▼

Update configuration state

Enables or disables a flag in an environment without modifying other settings.

Request

PUT /v2/applications/{applicationId}/flags/{flagId}/configuration/environments/{environmentId}/configstate▼

Request body

{
  "enabled": true
}▼

Example

curl -X PUT \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c/configuration/environments/e5c8d3e0-9f6b-5d4f-c2e7-b0f4e8d6c9e3/configstate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'▼

Clone flag configuration

Copies a flag configuration from one environment to another.

Request

POST /v2/applications/{applicationId}/flags/{flagId}/environment/{environmentId}/clone▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID.
`flagId`	string	Required. The flag ID.
`environmentId`	string	Required. The source environment ID.

applicationId

string

Required. The application ID.

flagId

string

Required. The flag ID.

environmentId

string

Required. The source environment ID.

Request body

{
  "targetEnvironmentId": "e6d9e4f1-0a7c-6e5a-d3f8-c1f5e9d7c0f4"
}▼

Example

curl -X POST \
  "https://api.cloudbees.io/v2/applications/a3b7c5d9-2f4e-8a1c-b6d4-e9f3a7b5c8d1/flags/f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c/environment/e5c8d3e0-9f6b-5d4f-c2e7-b0f4e8d6c9e3/clone" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetEnvironmentId": "e6d9e4f1-0a7c-6e5a-d3f8-c1f5e9d7c0f4"}'▼

List flag configurations

Retrieves configurations for all flags in an environment.

Request

GET /v2/applications/{applicationId}/environments/{environmentId}/configuration▼

Path parameters

Parameter Type Description

Parameter	Type	Description
`applicationId`	string	Required. The application ID.
`environmentId`	string	Required. The environment ID.

applicationId

string

Required. The application ID.

environmentId

string

Required. The environment ID.

Response

{
  "flagConfigurations": [
    {
      "flagId": "f7d3c8a1-4b2e-5f9a-b6c4-e1d8f3a7b5c2",
      "flagName": "default.newFeature",
      "description": "New feature flag",
      "labels": ["frontend"],
      "configuration": {
        "enabled": true,
        "defaultValue": false,
        "conditions": []
      }
    }
  ]
}▼

Condition structure

Conditions define when a flag returns a specific value. Each condition contains:

A logical operator wrapper (allOf or anyOf) that groups one or more criteria.
A flagValue field specifying what value to return when the condition matches.

Conditions are evaluated in order until one matches. If no condition matches, the defaultValue is used.

Basic structure

{
  "allOf": [
    {
      // condition criteria
    }
  ],
  "flagValue": true
}▼

Field Type Description

Field	Type	Description
`allOf`	array	All criteria must match (AND logic).
`anyOf`	array	At least one criterion must match (OR logic).
`flagValue`	any	Value to return when condition matches.

allOf

array

All criteria must match (AND logic).

anyOf

array

At least one criterion must match (OR logic).

flagValue

any

Value to return when condition matches.

Property condition

Test custom property values:

{
  "allOf": [
    {
      "property": {
        "operator": "eq",
        "name": "subscription_plan",
        "operand": "enterprise"
      }
    }
  ],
  "flagValue": true
}▼

Field Type Description

Field	Type	Description
`property.name`	string	Custom property name.
`property.operator`	string	Comparison operator (see operators reference below).
`property.operand`	any	Value to compare against (not required for `is-true`, `is-false`, `is-undefined`).
`property.operands`	array	Array of values for `in-array` operator.

property.name

string

Custom property name.

property.operator

string

Comparison operator (see operators reference below).

property.operand

any

Value to compare against (not required for is-true, is-false, is-undefined).

property.operands

array

Array of values for in-array operator.

Property with multiple values

Use the in-array operator to match any value in a list:

{
  "allOf": [
    {
      "property": {
        "operator": "in-array",
        "name": "region",
        "operands": ["us-west", "us-east", "eu-west"]
      }
    }
  ],
  "flagValue": true
}▼

Boolean property check

{
  "allOf": [
    {
      "property": {
        "operator": "is-true",
        "name": "isPremiumUser"
      }
    }
  ],
  "flagValue": true
}▼

Target group condition

Target users based on target group membership:

{
  "allOf": [
    {
      "allOf": [
        {
          "group": {
            "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
          }
        }
      ]
    }
  ],
  "flagValue": true
}▼

Multiple target groups (OR logic)

{
  "allOf": [
    {
      "anyOf": [
        {
          "group": {
            "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
          }
        },
        {
          "group": {
            "id": "a8f5b2c9-7e4d-4a1c-9b6e-3f8d7c5e4b2a"
          }
        }
      ]
    }
  ],
  "flagValue": true
}▼

Application version targeting

Target specific application versions using semantic versioning with the rox.app_release property:

{
  "allOf": [
    {
      "property": {
        "name": "rox.app_release",
        "operator": "semver-gte",
        "operand": "3.0.0"
      }
    }
  ],
  "flagValue": true
}▼

Dependency condition

Make a flag depend on another flag’s value:

{
  "allOf": [
    {
      "flag": {
        "name": "default.masterSwitch",
        "value": true
      }
    }
  ],
  "flagValue": true
}▼

Combining multiple criteria

Use allOf to require all criteria match (AND logic):

{
  "allOf": [
    {
      "allOf": [
        {
          "group": {
            "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
          }
        }
      ]
    },
    {
      "property": {
        "name": "rox.app_release",
        "operator": "semver-gte",
        "operand": "2.0.0"
      }
    },
    {
      "property": {
        "operator": "eq",
        "name": "region",
        "operand": "us-west"
      }
    }
  ],
  "flagValue": true
}▼

Use anyOf to match any criterion (OR logic):

{
  "anyOf": [
    {
      "allOf": [
        {
          "group": {
            "id": "f2331003-0bed-44ac-a8da-3e0367112dcb"
          }
        }
      ]
    },
    {
      "property": {
        "operator": "eq",
        "name": "tier",
        "operand": "premium"
      }
    }
  ],
  "flagValue": true
}▼

Property operators reference

Operator Description

Operator	Description
`is-true`	Boolean property is true.
`is-false`	Boolean property is false.
`is-undefined`	Property has no value.
`eq`	Value equals the operand.
`ne`	Value does not equal the operand.
`gt`	Value is greater than the operand.
`gte`	Value is greater than or equal to the operand.
`lt`	Value is less than the operand.
`lte`	Value is less than or equal to the operand.
`in-array`	Value is in the provided array (use `operands` field).
`regex`	Value matches the regular expression pattern.
`semver-eq`	Semantic version equals the operand.
`semver-ne`	Semantic version does not equal the operand.
`semver-gt`	Semantic version is greater than the operand.
`semver-gte`	Semantic version is greater than or equal to the operand.
`semver-lt`	Semantic version is less than the operand.
`semver-lte`	Semantic version is less than or equal to the operand.

is-true

Boolean property is true.

is-false

Boolean property is false.

is-undefined

Property has no value.

eq

Value equals the operand.

ne

Value does not equal the operand.

gt

Value is greater than the operand.

gte

Value is greater than or equal to the operand.

lt

Value is less than the operand.

lte

Value is less than or equal to the operand.

in-array

Value is in the provided array (use operands field).

regex

Value matches the regular expression pattern.

semver-eq

Semantic version equals the operand.

semver-ne

Semantic version does not equal the operand.

semver-gt

Semantic version is greater than the operand.

semver-gte

Semantic version is greater than or equal to the operand.

semver-lt

Semantic version is less than the operand.

semver-lte

Semantic version is less than or equal to the operand.

Percentage rollouts

Configure percentage-based rollouts using split values:

{
  "enabled": true,
  "defaultValue": [
    {
      "percentage": 50,
      "option": true
    },
    {
      "percentage": 50,
      "option": false
    }
  ],
  "conditions": []
}▼

Percentages must sum to 100.

Scheduled rollouts

Configure time-based rollouts (Boolean flags only):

{
  "enabled": true,
  "defaultValue": [
    {
      "percentage": 0,
      "from": "2024-03-01T00:00:00Z"
    },
    {
      "percentage": 50,
      "from": "2024-03-08T00:00:00Z"
    },
    {
      "percentage": 100,
      "from": "2024-03-15T00:00:00Z"
    }
  ],
  "conditions": []
}▼

Flag configurations API

Get flag configuration

Request

Path parameters

Response

Example

Update flag configuration

Request

Path parameters

Request body

Response

Example

Patch flag configuration

Request

Request body

Example

Update configuration state

Request

Request body

Example

Clone flag configuration

Request

Path parameters

Request body

Example

List flag configurations

Request

Path parameters

Response

Condition structure

Basic structure

Property condition

Property with multiple values

Boolean property check

Target group condition

Multiple target groups (OR logic)

Application version targeting

Dependency condition

Combining multiple criteria

Property operators reference

Percentage rollouts

Scheduled rollouts

Next steps