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": [
      {
        "group": {
          "name": "BetaUsers"
        },
        "value": 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": [
    {
      "group": {
        "name": "BetaUsers"
      },
      "value": true
    },
    {
      "group": {
        "name": "InternalTeam"
      },
      "value": 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": [
      {
        "group": {
          "name": "BetaUsers"
        },
        "value": 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 is an object with the following structure:

Target group condition

{
  "group": {
    "name": "BetaUsers",
    "operator": "or"
  },
  "value": true
}▼

Property condition

{
  "property": {
    "propertyConditions": [
      {
        "property": "subscription_plan",
        "operator": "eq",
        "operand": "enterprise"
      }
    ]
  },
  "value": true
}▼

Version condition

{
  "version": {
    "operator": "semver-gte",
    "semver": "3.0.0"
  },
  "value": true
}▼

Dependency condition

{
  "dependency": {
    "flag": "default.masterSwitch",
    "value": true
  },
  "value": true
}▼

Combined conditions

Use acrossTypesLogicGate to combine multiple condition types:

{
  "group": {
    "name": "BetaUsers"
  },
  "version": {
    "operator": "semver-gte",
    "semver": "2.0.0"
  },
  "acrossTypesLogicGate": "and",
  "value": true
}▼

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

Target group condition

Property condition

Version condition

Dependency condition

Combined conditions

Percentage rollouts

Scheduled rollouts

Next steps